betaFeedback

WorksComputer Science

Sheaf-MPNN: A Library for Sheaf Neural Networks as Message Passing

Abstract

Standard Graph Neural Networks (GNNs) implicitly assume that neighboring nodes share the same feature space, which contributes to oversmoothing and poor performance on heterophilic graphs. Sheaf Neural Networks (SNNs) remove this assumption by giving each node and edge its own vector space and learning restriction maps that transform features as they move between neighbors. These maps define a sheaf Laplacian that drives diffusion over the graph, but existing implementations often assemble it explicitly as a global sparse block matrix, which adds memory and computational overhead and can hinder scalability. In this paper, we introduce Sheaf-MPNN, a PyTorch Geometric library that reformulates sheaf diffusion as local incidence-wise transport and aggregation, eliminating the need to construct the global Laplacian. Sheaf-MPNN implements fifteen families of SNNs under a unified message-passing framework, each supporting both homogeneous and heterogeneous graphs, and directed and undirected settings, with diagonal, general, orthogonal, and low-rank restriction maps and attention-based predictors. We further provide a unified benchmarking suite covering node- and graph-level tasks, heterogeneous graph learning, and computational efficiency, enabling systematic and reproducible comparisons across architectures. We establish theoretical equivalence between these message-passing formulations and their original counterparts and identify the architectural mechanisms needed to preserve their propagation dynamics. This unified perspective provides a principled foundation for implementing, comparing, and extending sheaf-based architectures within standard graph learning frameworks. Source code is available at https://github.com/alessioborgi/sheaf-mpnn.

∗^{*}Corresponding Author.

©2026 Alessio Borgi et al..

License: CC-BY 4.0, see https://creativecommons.org/licenses/by/4.0/.

Introduction

Graph Neural Networks (GNNs) typically learn graph-structured representations through the message-passing paradigm, in which nodes update their representations by aggregating information from their neighbours [31]. Sheaf Neural Networks (SNNs) enrich graph learning with cellular sheaves, which assign local vector spaces, or stalks, to nodes and edges, together with linear restriction maps for each node–edge incidence. These maps transport node representations into a shared edge stalk, where neighbouring signals can be compared. SNNs use this structure to define propagation operators, commonly based on the sheaf Laplacian, that allow neighbouring representations to remain consistent after transport even when their original features differ [36, 9]. Subsequent research has explored how sheaves are constructed [6, 16, 30], how information propagates through them [53, 7, 56, 5, 11, 12], and extensions to different graph structures and feature spaces [14, 27, 25, 43, 10, 49, 2, 54]. Despite their common foundations, these models differ in their restriction maps, propagation operators, normalization schemes, and update rules. Appendix A surveys these developments.

A common computational challenge arises from the explicit construction of sheaf operators. Existing SNN implementations assemble the global sheaf Laplacian as a sparse block matrix and apply it to the stacked node representations. For a graph with nn nodes and dd-dimensional stalks, this produces an nd×ndnd \times nd operator whose nonzero blocks may contain dense d×dd \times d matrices. Constructing and storing this operator introduces additional memory and computational overhead, particularly for large graphs or higher-dimensional stalks. Yet the action of the sheaf Laplacian is inherently local: each edge compares its endpoint representations after transport into a shared stalk, and the resulting contributions are mapped back to the incident nodes and aggregated. This suggests that sheaf propagation can be implemented directly through local message passing, without explicitly assembling the global Laplacian. Such a formulation removes the need for operator assembly, although its practical efficiency depends on the implementation and must be evaluated empirically. Motivated by this observation, we introduce Sheaf-MPNN, a PyTorch Geometric library that implements sheaf propagation through local incidence-wise transport and aggregation. By expressing different SNN architectures within a common computational interface, Sheaf-MPNN facilitates their implementation, reuse, and comparison while integrating them with established graph learning tools. The library provides 15 families of SNNs, each with homogeneous and heterogeneous variants, and supports directed and undirected graph settings. It includes diagonal, general, orthogonal, and low-rank restriction maps, together with attention-based map predictors where applicable. To enable systematic evaluation, we also provide a unified benchmarking suite, covering more than 20 datasets, including node- and graph-level learning, heterogeneous graph benchmarks, and computational efficiency, with shared experimental configurations and reproducible evaluation protocols.

Beyond the library itself, we also develop the unified Sheaf Message Passing Neural Network (Sheaf-MPNN) theoretical framework that characterises how existing sheaf architectures can be expressed through local message passing. We derive explicit message-passing formulations for 15 architecture configurations and establish their theoretical equivalence to the original models, identifying the mechanisms required to preserve their propagation dynamics. These include augmented node states, type-conditioned restriction maps, and directed aggregation rules. We further show that the SheafPool graph-level readout ([14]) can be formulated within the same framework by aggregating locally aligned node representations into a receive-only virtual node. Together, our contribution provides a common theoretical and computational foundation for implementing, comparing, and extending sheaf-based graph learning. Appendix C details the supported architectures, implementation choices, and normalization conventions.

Sheaf Message Passing in a Nutshell

Let G=(V,E)\mathcal{G}=(\mathcal{V},\mathcal{E}) be a finite undirected graph without self-loops, and let F\mathcal{F} be a cellular sheaf assigning finite-dimensional inner-product spaces F(u)\mathcal{F}(u) and F(e)\mathcal{F}(e) to nodes and edges, with linear restriction maps Fu⊴e:F(u)→F(e)\mathcal{F}_{u\unlhd e}:\mathcal{F}(u)\to\mathcal{F}(e) for each incidence u⊴eu\unlhd e ([21, 36]). Node signals belong to C0(G,F)=⨁u∈VF(u)C^0(\mathcal{G},\mathcal{F})=\bigoplus_{u\in\mathcal{V}}\mathcal{F}(u). In orthonormal stalk bases, the sheaf Laplacian acts on x∈C0(G,F)\mathbf{x}\in C^0(\mathcal{G},\mathcal{F}) as:

(LFx)u=∑e={u,v}∈EFu⊴eT(Fu⊴exu−Fv⊴exv).(1)(\mathbf{L}_{\mathcal{F}}\mathbf{x})_u=\sum_{e=\{u,v\}\in\mathcal{E}}\mathcal{F}_{u\unlhd e}^{\mathsf{T}}\left(\mathcal{F}_{u\unlhd e}\mathbf{x}_u-\mathcal{F}_{v\unlhd e}\mathbf{x}_v\right). \tag*{(1)}

Here, each term measures disagreement in the shared edge stalk and transports it back to the receiving node, revealing the Laplacian as a local aggregation operator. We generalise this observation into a Sheaf Message Passing Neural Network (Sheaf-MPNN). Assuming stalks of dimension dd and ff feature channels, each node has state xu(k)∈Rd×f\mathbf{x}_u^{(k)}\in\mathbb{R}^{d\times f} at layer kk. A SheafMPNN transforms node states, computes interactions in edge stalks, aggregates the resulting messages, and updates node representations as:

zu(k)=W1(k)xu(k)W2(k),(2)\mathbf{z}_u^{(k)}=\mathbf{W}_1^{(k)}\mathbf{x}_u^{(k)}\mathbf{W}_2^{(k)}, \tag*{(2)}
mu⊴e(k)=ψe(Fv⊴ezv(k),Fu⊴ezu(k),evu),(3)\mathbf{m}_{u\unlhd e}^{(k)}=\psi_e\left(\mathcal{F}_{v\unlhd e}\mathbf{z}_v^{(k)},\mathcal{F}_{u\unlhd e}\mathbf{z}_u^{(k)},\mathbf{e}_{vu}\right), \tag*{(3)}
mu(k+1)=⨁e={u,v}∈Eωuv(k)Fu⊴e⊤mu⊴e(k)(4)\mathbf{m}_{u}^{(k+1)}=\bigoplus_{e=\{u,v\}\in\mathcal{E}}\omega_{uv}^{(k)}\mathcal{F}^{\top}_{u\trianglelefteq e}\mathbf{m}_{u\trianglelefteq e}^{(k)} \tag*{(4)}
xu(k+1)=φu(xu(k),mu(k+1)).(5)\mathbf{x}_{u}^{(k+1)}=\varphi_{u}\left(\mathbf{x}_{u}^{(k)},\mathbf{m}_{u}^{(k+1)}\right). \tag*{(5)}

Here, W1(k)∈Rd×d\mathbf{W}_{1}^{(k)}\in\mathbb{R}^{d\times d} and W2(k)∈Rf×f\mathbf{W}_{2}^{(k)}\in\mathbb{R}^{f\times f} mix stalk coordinates and feature channels, respectively. The function ψe\psi_{e} computes interactions between transported representations, optionally incorporating edge features euv\mathbf{e}_{uv}. Each message is weighted by ωuv(k)\omega_{uv}^{(k)}, pulled back through Fu⊴e⊤\mathcal{F}^{\top}_{u\trianglelefteq e}, aggregated by ⨁\bigoplus, and combined with the current state through φu\varphi_{u}. Restriction maps may be learned at each layer, with their layer index omitted for clarity. The construction is equivariant to node relabelling when aggregation is permutation invariant, and the map predictors and update functions are shared and independent of node ordering. Figure 1 illustrates the distinction from standard message passing. Sheaf diffusion is recovered by setting ψe(a,b)=b−a\psi_{e}(a,b)=b-a, ωuv(k)=1\omega_{uv}^{(k)}=1, and using sum aggregation, yielding Equation (1) on the transformed features. Normalization is incorporated through Fu⊴eNu\mathcal{F}_{u\trianglelefteq e}N_{u} and its transpose, where the implementation uses Nu=(Du+I)−1/2N_{u}=(D_{u}+I)^{-1/2} with Du=∑e∋uFu⊴e⊤Fu⊴eD_{u}=\sum_{e\ni u}\mathcal{F}^{\top}_{u\trianglelefteq e}\mathcal{F}_{u\trianglelefteq e} (Appendix C.§ 3). Conversely, identity restrictions and identity pre-transformations recover standard MPNNs. The framework also accommodates heterogeneous graphs through type-conditioned restriction-map predictors (Appendix § 5.0.2.§ 3) and directed graphs through incoming-arc aggregation (Appendix § 5.0.2.§ 4). Explicit directed propagation is necessary because an undirected edge yields cross-edge blocks Fu⊴e⊤Fv⊴e\mathcal{F}^{\top}_{u\trianglelefteq e}\mathcal{F}_{v\trianglelefteq e} and Fv⊴e⊤Fu⊴e\mathcal{F}^{\top}_{v\trianglelefteq e}\mathcal{F}_{u\trianglelefteq e} that are transposes, rather than independent directional operators. We formalise the recovery of existing architectures below.

Comparison of standard MPNN and SheafMPNN message passing

Figure 1. Sheaf Message Passing Neural Network (SheafMPNN). Neighbourhood update at node 0 (red), with neighbouring nodes in blue. (Left) A standard MPNN computes messages m0im_{0i} (green) from neighbouring node states and aggregates them at node 0. (Right) A SheafMPNN transports both endpoint representations into the shared edge stalk F(e0i)\mathcal{F}(e_{0i}) (boxes) through restriction maps (dashed grey arrows). The function ψ\psi computes their interaction, and the resulting message is pulled back through F0⊴e0i⊤\mathcal{F}^{\top}_{0\trianglelefteq e_{0i}} and aggregated at node 0 (solid black arrows).

Theorem 1 The following architectures admit the SheafMPNN representation in Equations (2)–(5), with matching normalization and updates: (i) Neural Sheaf Diffusion; (ii) standard MPNNs, via identity restrictions and identity pre-transform; (iii) SheafAN, Res-

SheafAN, and sheaf adjacency propagation; and (iv) Neural Sheaf Propagation, on an augmented sheaf with node stalks R2d\mathbb{R}^{2d} and edge stalks Rd\mathbb{R}^{d}.

Appendix § 5.0.2 proves Theorem 1 and extends the framework to diagonal, general, orthogonal, low-rank, and attention-generated NSD restrictions, as well as to all the sheaf-variants (Theorems 6, 10, 13, 15, and 19–23).

The computational cost of SheafMPNN reflects the locality of its propagation operator: the transport and aggregation require O(∣E∣d2f)O(|\mathcal{E}|d^{2}f) operations, with O(∣E∣d2+∣E∣df+ndf)O(|\mathcal{E}|d^{2} + |\mathcal{E}|df + ndf) memory for restriction maps, edge messages, and node states when messages are materialised. These bounds exclude map prediction, channel mixing, and block normalization. So, at the end, we evaluate the sheaf Laplacian entirely through local operations, without assembling its global nd×ndnd \times nd matrix representation (Remark 9).

Library Design and Usage

Built on PyTorch ([45]) and PyTorch Geometric ([26]), Sheaf-MPNN provides reusable sheaf message-passing layers and end-to-end model wrappers through a unified interface (Appendix C.§ 2). The following example illustrates node classification using orthogonal Neural Sheaf Diffusion:

from torch_geometric.datasets import HeterophilousGraphDataset
from sheaf_mpnn.nsd import NSDModel, NSDVariant

data = HeterophilousGraphDataset("data", name="Roman-empire")[0]
model = NSDModel(in_channels=data.num_features, out_channels=18,
                 hidden_dim=16, num_layers=4, stalk_dim=4,
                 variant=NSDVariant.ORTHOGONAL)
out = model(data.x, data.edge_index)  # [num_nodes, 18]

The accompanying sheaf command-line interface supports reproducible experiments across more than 20 datasets, Optuna-based hyperparameter optimization ([1]), and computational efficiency comparisons against reference implementations. Appendix C details the package structure, model interfaces, and experimental tooling.

Related Software

General-purpose frameworks such as PyTorch Geometric ([26]) and DGL ([55]) provide message-passing abstractions without native support for cellular sheaves. TopoX ([34]) supports higher-order topological domains, including operator-based sheaf models, while existing SNN implementations ([9, 7, 14]) primarily target individual architectures and often rely on explicit sheaf-Laplacian assembly. In contrast, Sheaf-MPNN provides a reusable, Laplacian-free message-passing implementation across a broad family of SNNs, complemented by unified benchmarking tools and theoretical equivalence results.

Availability

Sheaf-MPNN is publicly available at https://github.com/alessioborgi/sheaf-mpnn under the CC-BY 4.0 license, together with documentation and tutorial notebooks. Appendix C provides implementation details, supported architectures, and experimental configurations.

Primer on Cellular Sheaves and Sheaf Neural Networks

This appendix introduces in a deeper way the Sheaf Neural Networks (SNNs) and places the Sheaf-MPNN library within the literature. It first explains how a cellular sheaf generalizes the graph Laplacian and why diffusion on a sheaf avoids the classical failure modes of message passing, and then reviews how the field has developed. For fuller treatments we refer to Curry [21] and Rosiak [50] for cellular sheaf theory, to Hansen and Ghrist [38] for the spectral theory of the sheaf Laplacian, and to the survey of Ayzenberg et al. [4] for sheaf theory in machine learning more broadly.

From Message Passing to Sheaves

Message Passing Neural Networks. A message passing neural network (Gilmer et al. [31]) updates the representation xu\mathbf{x}_u of each node uu of a graph G=(V,E)\mathcal{G} = (\mathcal{V}, \mathcal{E}) by aggregating the states of its neighbours N(u)\mathcal{N}(u):

xu(t+1)=Update⁡(t)(xu(t),Aggregate⁡(t)({xv(t):v∈N(u)})).(6)\mathbf{x}_u^{(t+1)} = \operatorname{Update}^{(t)}\left(\mathbf{x}_u^{(t)}, \operatorname{Aggregate}^{(t)}\left(\left\{\mathbf{x}_v^{(t)} : v \in\mathcal{N}(u)\right\}\right)\right). \tag*{(6)}

This update assumes that all node features live in one shared vector space, so that neighbouring features can be compared and averaged directly. The assumption is harmless when connected nodes tend to be similar, but it underlies two well-known failures. Repeated low-pass averaging drives features towards a constant signal as depth grows, a phenomenon known as oversmoothing ([15, 51]); and on heterophilic graphs, where neighbours tend to belong to different classes, averaging erases the very signal that separates them. Cellular sheaves remove the assumption at its source: every node and every edge receives its own vector space, and learnable linear maps decide how signals are compared across each edge.

Cellular Sheaves. A sheaf attaches data to the pieces of a space, together with rules stating how the data on overlapping pieces must agree. It therefore describes when local information can be glued into a consistent global picture. Cellular sheaves make this idea discrete by attaching vector spaces to the cells of a cell complex and linear maps to the relations between them. On a graph, the cells are the vertices and the edges, and each incidence u⊴eu \trianglelefteq e, read as “uu is a face of ee”, carries a linear map that moves data from the vertex to the edge where it is compared with data from the other endpoint.

Definition 2 (Cellular Sheaf on a Graph). A cellular sheaf ([52, 21]) on an undirected graph G=(V,E)\mathcal{G} = (\mathcal{V}, \mathcal{E}) assigns a finite-dimensional inner-product space (the stalk) F(u)\mathcal{F}(u) to each vertex u∈Vu \in\mathcal{V} and F(e)\mathcal{F}(e) to each edge e∈Ee \in\mathcal{E}, together with linear restriction maps Fu⊴e:F(u)→F(e)\mathcal{F}_{u \trianglelefteq e} : \mathcal{F}(u) \to\mathcal{F}(e) for each incident node–edge pair u⊴eu \trianglelefteq e. Stacking vertex and edge stalks yields the 00- and 11-cochain spaces C0(G,F):=⨁u∈VF(u)C^0(\mathcal{G},\mathcal{F}) := \bigoplus_{u \in\mathcal{V}} \mathcal{F}(u) and C1(G,F):=⨁e∈EF(e)C^1(\mathcal{G},\mathcal{F}) := \bigoplus_{e \in\mathcal{E}} \mathcal{F}(e), respectively.

An intuitive reading comes from opinion dynamics (Hansen and Ghrist [39]). Each node stalk is a private opinion space, each edge stalk is a shared space for the conversation along that edge, and Fu⊴e\mathcal{F}_{u \trianglelefteq e} describes how uu expresses its opinion in that conversation. This means that two neighbours, instead of agreeing when their raw features do, they agree along ee when their expressed opinions coincide, Fu⊴exu=Fv⊴exv\mathcal{F}_{u \trianglelefteq e}\mathbf{x}_u = \mathcal{F}_{v \trianglelefteq e}\mathbf{x}_v. Disagreement is therefore measured only after both signals have been aligned in a common space, which is exactly what a heterophilic edge requires.

Orienting each edge as e=(u→v)e=(u\to v), the coboundary is δ:C0(G,F)→C1(G,F)\delta:C^0(\mathcal{G},\mathcal{F})\to C^1(\mathcal{G},\mathcal{F}), and the δ(x)e:=Fv⊴exv−Fu⊴exu\delta(\mathbf{x})_e:=\mathcal{F}_{v\trianglelefteq e}\mathbf{x}_v-\mathcal{F}_{u\trianglelefteq e}\mathbf{x}_u records this disagreement edge by edge. Resulting from this, the 0-cochain with δ(x)=0\delta(\mathbf{x})=0 is a global section: a configuration that is consistent across the whole graph. The sheaf Laplacian LF:=δ⊤δL_{\mathcal{F}}:=\delta^\top\delta [38] acts node-wise as:

LF(x)u=∑u,v⊴eFu⊴e⊤(Fu⊴exu−Fv⊴exv).(7)L_{\mathcal{F}}(\mathbf{x})_u=\sum_{u,v\trianglelefteq e}\mathcal{F}_{u\trianglelefteq e}^{\top}\left(\mathcal{F}_{u\trianglelefteq e}\mathbf{x}_u-\mathcal{F}_{v\trianglelefteq e}\mathbf{x}_v\right). \tag*{(7)}

It is symmetric positive semi-definite, with diagonal blocks ∑u⊴eFu⊴e⊤Fu⊴e\sum_{u\trianglelefteq e}\mathcal{F}_{u\trianglelefteq e}^{\top}\mathcal{F}_{u\trianglelefteq e} and off-diagonal blocks −Fu⊴e⊤Fv⊴e-\mathcal{F}_{u\trianglelefteq e}^{\top}\mathcal{F}_{v\trianglelefteq e}, and its kernel is exactly the space of global sections. Its normalized form is ΔF:=D−1/2LFD−1/2\Delta_{\mathcal{F}}:=D^{-1/2}L_{\mathcal{F}}D^{-1/2}, where DD is the block diagonal of LFL_{\mathcal{F}}. We take all stalks to be Rd\mathbb{R}^d, so that LF∈Rnd×ndL_{\mathcal{F}}\in\mathbb{R}^{nd\times nd} for a graph with nn nodes. When every restriction map is the identity, Equation (7) reduces to the graph Laplacian ∑v∈N(u)(xu−xv)\sum_{v\in\mathcal{N}(u)}(\mathbf{x}_u-\mathbf{x}_v) and the global sections are the constant signals. Classical graph learning is thus the special case of the constant sheaf, which is how the blueprint of § 2 recovers standard MPNNs (Theorem 1).

Sheaf Diffusion and Neural Sheaf Diffusion. The sheaf Laplacian generates the diffusion x˙(t)=−ΔFx(t)\dot{\mathbf{x}}(t)=-\Delta_{\mathcal{F}}\mathbf{x}(t), which decreases the sheaf Dirichlet energy x⊤LFx=∥δx∥2\mathbf{x}^{\top}L_{\mathcal{F}}\mathbf{x}=\lVert\delta\mathbf{x}\rVert^2 and converges to the projection of the initial signal onto the global sections. For the constant sheaf these are the constant signals, so deep diffusion oversmooths. For a general sheaf they are shaped by the restriction maps, and may assign different features to neighbouring nodes as long as these agree after transport. Bodnar et al. [9] turned this observation into Neural Sheaf Diffusion (NSD). They proved that suitable sheaves let diffusion linearly separate classes in settings, including heterophilic ones, where graph diffusion provably cannot, and they made the sheaf learnable. NSD stacks the stalk signals into X∈Rnd×f\mathbf{X}\in\mathbb{R}^{nd\times f} with ff feature channels, predicts the map of every incidence from the features of its two endpoints, Fu⊴e(t)=Φ(t)(xu∥xv)\mathcal{F}_{u\trianglelefteq e}^{(t)}=\Phi^{(t)}(\mathbf{x}_u\mathbin\Vert\mathbf{x}_v), as a diagonal, orthogonal, or general matrix, and performs the step:

X(t+1)=X(t)−σ(ΔF(t)(In⊗W1(t))X(t)W2(t)),(8)\mathbf{X}^{(t+1)}=\mathbf{X}^{(t)}-\sigma\left(\Delta_{\mathcal{F}^{(t)}}\left(\mathbf{I}_n\otimes\mathbf{W}_1^{(t)}\right)\mathbf{X}^{(t)}\mathbf{W}_2^{(t)}\right), \tag*{(8)}

where W1(t)\mathbf{W}_1^{(t)} and W2(t)\mathbf{W}_2^{(t)} act on the stalk and channel dimensions, respectively. This is the update that Sheaf-MPNN evaluates without materializing ΔF(t)\Delta_{\mathcal{F}^{(t)}} (Theorem 1 and Appendix C.§ 3).

Sheaf Neural Network Literature

Sheaf-based learning grew out of applied topology. Hansen and Ghrist [38] developed the spectral theory of the sheaf Laplacian, Hansen and Ghrist [37] showed how to learn it from smooth signals, and Hansen and Ghrist [39] interpreted sheaf diffusion as opinion dynamics. Hansen and Gebhart [36] then proposed the first sheaf neural networks, with hand-crafted sheaves, and Gebhart et al. [29] recast knowledge-graph embedding as learning an approximate global section of a knowledge sheaf, an idea later used to embed new entities by harmonic extension ([20]). NSD ([9]) made the sheaf itself learnable and supplied the theory on which most subsequent work builds.

A first line of work asks how the sheaf should be obtained. Connection-Laplacian networks ([6]) compute orthogonal maps in preprocessing by aligning local tangent spaces, and tangent-bundle networks [8] show that discretizing convolution on a manifold’s tangent bundle yields a principled sheaf model. Signal-processing methods learn restriction maps, or entire connection graphs, directly from data [22, 23]. Bayesian SNNs [30] place a variational distribution over sheaves, PAC-Bayes bounds guide the spectral optimization of the learned operator [19], and eigenvectors of a learned sheaf Laplacian serve as positional encodings for ordinary GNNs (He et al., 2023). To interpret what a learned sheaf encodes, the Bochner–Weitzenböck decomposition of [32] splits the sheaf Laplacian into a positive semi-definite part and a block-diagonal curvature term, which describes the learned geometry locally rather than through the global spectrum. However, two recent studies temper the enthusiasm: Caralt et al. [17] find that the fixed identity sheaf is competitive on the standard heterophily benchmarks, and the inductive benchmark of Fiorini et al. [28] finds that the choice of restriction maps matters most, yet that SNNs do not surpass the strongest baselines. Both suggest that the value of a learned sheaf depends strongly on the task.

A second line changes how signals move on the sheaf. Continuous NSD models the dynamics of Eq. (8) as continuous time diffusion [9], Sheaf attention networks weight the transported neighbours [7], Neural Sheaf Propagation adopts a second-order recurrence [53], and nonlinear [56] and joint [16] diffusion modify the interaction law itself. Polynomial filters of the sheaf Laplacian enlarge the receptive field of a single layer [11], while Deep NSD replaces the Laplacian with a sheaf adjacency operator, complemented with per-stalk gating, odd activation and layer normalization, to keep signals informative across many layers [12]. Long-range communication has become a central theme. Cooperative SNNs let each node decide independently whether to send or receive information [48]; SheafDEQ formulate sheaf propagation as an equilibrium with convergence guarantees [13]; oscillatory dynamics over sheaves propagate information through second-order, wave-like updates [54]; and sheaf effective resistance shows that over-squashing can be reduced by changing the sheaf rather than rewiring the graph [33]. Bundle neural networks [5] restrict the sheaf to flat vector bundles and replace message passing with heat-kernel diffusion, and topological attention [2] reinterprets multi-head attention as transport through quiver representations, whose off-diagonal routes mix heads before aggregation.

Sheaves also offer a natural place to encode richer relational structure. Heterogeneous SNNs condition the restriction maps on node and edge types and introduce the gauge-invariant SheafPool readout for graph classification [14]. Directed SNNs generalize the cellular sheaf to account for edge orientation [27], temporal SNNs give each node a time-varying orthogonal frame for link prediction on dynamic graphs [3], and hierarchical sheaf pooling coarsens graphs using low-frequency modes of cluster-internal sheaf Laplacians [44]. Further work leaves graphs or Euclidean stalks behind. Sheaf hypergraph networks [24] extend incidence-based transport to group interactions; follow-ups construct hypergraph sheaf Laplacians from symmetric simplicial lifts [18], add directed hyperedges [43], and bring sheaves to higher-order message passing in topological deep learning Hume and Liò, 2025). Copresheaf networks Hajij et al., [35] place sheaf models within a broader framework that also covers other deep learning architectures. Other models change the stalks themselves, carrying Gaussian distributions Ribeiro et al., [49], symmetric positive-definite matrices with manifold-compatible operators Peng et al., [46], Clifford-algebra multivectors Kamiya and Nicholls, [42], or Euclidean-equivariant vector features Borgi et al., [10]. In each case the restriction maps, and not only the aggregation, must respect the structure of the stalks.

The SheafMPNN Blueprint Recovers Existing Sheaf Architectures

This appendix proves Theorem 1: each architecture listed there is an instance of the blueprint in Equations (2)–(5), so its layers can be evaluated by local message passing without materializing the sheaf Laplacian. It then extends the construction to polynomial, graph-level, heterogeneous, directed, cooperative, joint, bundle, and Bayesian models. Throughout, σ\sigma denotes a pointwise nonlinearity, Du=∑u⊴eFu⊴eTFu⊴e\mathbf{D}_u = \sum_{u\trianglelefteq e} \mathbf{F}_{u\trianglelefteq e}^{\mathsf{T}}\mathbf{F}_{u\trianglelefteq e} the block degree of node uu, and ΔF=D−1/2LFD−1/2\Delta_{\mathcal{F}} = \mathbf{D}^{-1/2}\mathcal{L}_{\mathcal{F}}\mathbf{D}^{-1/2} the normalized sheaf Laplacian. As in § 2, normalization is absorbed into the restriction maps by writing F^u⊴e:=Fu⊴eDu−1/2\widehat{\mathbf{F}}_{u\trianglelefteq e} := \mathbf{F}_{u\trianglelefteq e}\mathbf{D}_u^{-1/2}, so that:

[ΔFz]u=∑u,v⊴eF^u⊴eT(F^u⊴ezu−F^v⊴ezv).(9)[\Delta_{\mathcal{F}}\mathbf{z}]_u = \sum_{u,v\trianglelefteq e}\widehat{\mathbf{F}}_{u\trianglelefteq e}^{\mathsf{T}}\left(\widehat{\mathbf{F}}_{u\trianglelefteq e}\mathbf{z}_u-\widehat{\mathbf{F}}_{v\trianglelefteq e}\mathbf{z}_v\right). \tag*{(9)}

The release instead normalizes with Nu=(Du+Id)−1/2\mathbf{N}_u = (\mathbf{D}_u+\mathbf{I}_d)^{-1/2} (Appendix C.§ 3). Since Du+Id\mathbf{D}_u+\mathbf{I}_d is positive definite, this needs no invertible restriction map, and every construction below holds verbatim with Nu\mathbf{N}_u in place of Du−1/2\mathbf{D}_u^{-1/2}.

Theorem 1. The following architectures admit the SheafMPNN representation in Equations (2)–(5), with matching normalization and updates: (i) Neural Sheaf Diffusion; (ii) standard MPNNs, via identity restrictions and identity pre-transform; (iii) SheafAN, Res-SheafAN, and sheaf adjacency propagation; and (iv) Neural Sheaf Propagation, on an augmented sheaf with node stalks R2d\mathbb{R}^{2d} and edge stalks Rd\mathbb{R}^{d}.

In the following, we proof each part of Theorem 1 in turn, showing that the layer update of each architecture can be expressed in the form of Equation (5) with a suitable choice of message ψe\psi_e, aggregation ⨁\bigoplus, and update φu\varphi_u.

Proof of Theorem 1, Parts (i)–(ii): Neural Sheaf Diffusion. A layer of Neural Sheaf Diffusion (NSD) Bodnar et al., [9] computes:

Z(k)=(In⊗W1(k))X(k)W2(k),\mathbf{Z}^{(k)} = \left(\mathbf{I}_n \otimes\mathbf{W}_1^{(k)}\right)\mathbf{X}^{(k)}\mathbf{W}_2^{(k)},
X(k+1)=(1+ε(k))⊙X(k)−ασ(ΔF(k)Z(k)).(10)\mathbf{X}^{(k+1)} = \left(1+\boldsymbol{\varepsilon}^{(k)}\right)\odot\mathbf{X}^{(k)}-\alpha\sigma\left(\Delta_{\mathcal{F}^{(k)}}\mathbf{Z}^{(k)}\right). \tag*{(10)}

where ε(k)∈Rd\boldsymbol{\varepsilon}^{(k)}\in\mathbb{R}^{d} rescales each stalk dimension, broadcast across nodes and channels, and α\alpha is the diffusion step size. By Equation (9), the update at node uu is:

xu(k+1)=(1+ε(k))⊙xu(k)−ασ(∑u,v⊴eF^u⊴eT(F^u⊴ezu(k)−F^v⊴ezv(k)))\mathbf{x}_u^{(k+1)}=\left(1+\boldsymbol{\varepsilon}^{(k)}\right)\odot\mathbf{x}_u^{(k)}-\alpha\sigma\left(\sum_{u,v\trianglelefteq e}\widehat{\mathbf{F}}_{u\trianglelefteq e}^{\mathsf{T}}\left(\widehat{\mathbf{F}}_{u\trianglelefteq e}\mathbf{z}_u^{(k)}-\widehat{\mathbf{F}}_{v\trianglelefteq e}\mathbf{z}_v^{(k)}\right)\right)

with zu(k)=W1(k)xu(k)W2(k)z_u^{(k)} = \mathbf{W}_1^{(k)} \mathbf{x}_u^{(k)} \mathbf{W}_2^{(k)}. This is the blueprint with the normalized maps F^\hat{\mathcal{F}}, the message function ψe(a,b)=b−a\psi_e(a,b)=b-a in Equation (3), unit weights and sum aggregation in Equation (4), and the update φu(xu,mu)=(1+ϵ(k))⊙xu−ασ(mu)\varphi_u(\mathbf{x}_u,\mathbf{m}_u)=(1+\boldsymbol{\epsilon}^{(k)})\odot\mathbf{x}_u-\alpha\sigma(\mathbf{m}_u) in Equation (5). For part (ii), take every restriction map and both weight matrices to be identities. The transported states are then the raw node states, the message ψe(xv,xu,euv)\psi_e(\mathbf{x}_v,\mathbf{x}_u,\mathbf{e}_{uv}) and the aggregation ⨁\bigoplus are arbitrary, and the pullback is the identity, so the blueprint reduces to the general MPNN of Gilmer et al. [31].

Proof of Theorem 1, part (iii): Sheaf Attention. Let AF\mathbf{A}_{\mathcal{F}} be the block matrix whose (u,v)(u,v) block is Fu⊴e⊤Fv⊴e\mathcal{F}_{u\trianglelefteq e}^{\top}\mathcal{F}_{v\trianglelefteq e} for every edge e={u,v}e=\{u,v\} and zero otherwise, and let Λ^(k)\hat{\boldsymbol{\Lambda}}^{(k)} collect the attention coefficients Λuv=Attn⁡(xu(k),xv(k))\Lambda_{uv}=\operatorname{Attn}(\mathbf{x}_u^{(k)},\mathbf{x}_v^{(k)}), normalized over the neighbours of uu. A SheafAN layer (Barbero et al. [7]) computes:

X(k+1)=σ((Λ^(k)⊗1d11d1⊤)⊙AF(k))Z(k)(11)\mathbf{X}^{(k+1)}=\sigma\left(\left(\hat{\boldsymbol{\Lambda}}^{(k)}\otimes\mathbf{1}_{d_1}\mathbf{1}_{d_1}^{\top}\right)\odot\mathbf{A}_{\mathcal{F}(k)}\right)\mathbf{Z}^{(k)} \tag*{(11)}

which at node uu reads xu(k+1)=σ(∑u,v⊴eΛuvFu⊴e⊤Fv⊴ezv(k))\mathbf{x}_u^{(k+1)}=\sigma\left(\sum_{u,v\trianglelefteq e}\Lambda_{uv}\mathcal{F}_{u\trianglelefteq e}^{\top}\mathcal{F}_{v\trianglelefteq e}\mathbf{z}_v^{(k)}\right). This is the blueprint with the message ψe(a,b)=a\psi_e(a,b)=a, so that mu⊴e=Fv⊴ezv(k)\mathbf{m}_{u\trianglelefteq e}=\mathcal{F}_{v\trianglelefteq e}\mathbf{z}_v^{(k)}, the weights ωuv=Λuv\omega_{uv}=\Lambda_{uv}, sum aggregation, and the update φu(xu,mu)=σ(mu)\varphi_u(\mathbf{x}_u,\mathbf{m}_u)=\sigma(\mathbf{m}_u). When the attention coefficients are normalized by a softmax over the neighbourhood, the normalization is itself local: each edge also sends its unnormalized score, both quantities are summed, and the update divides one by the other, as in graph attention.

Res-SheafAN adds a residual connection and a skip rescaling to the SheafAN update, so that the layer computes:

X(k+1)=(1+ϵ(k))⊙X(k)+σ(((Λ^(k)⊗1d11d1⊤)⊙AF(k)−I)Z(k))\mathbf{X}^{(k+1)}=(1+\boldsymbol{\epsilon}^{(k)})\odot\mathbf{X}^{(k)}+\sigma\left(\left(\left(\hat{\boldsymbol{\Lambda}}^{(k)}\otimes\mathbf{1}_{d_1}\mathbf{1}_{d_1}^{\top}\right)\odot\mathbf{A}_{\mathcal{F}(k)}-\mathbf{I}\right)\mathbf{Z}^{(k)}\right)

so that xu(k+1)=(1+ϵ(k))⊙xu(k)+σ(∑u,v⊴eΛuvFu⊴e⊤Fv⊴ezv(k)−zu(k))\mathbf{x}_u^{(k+1)}=(1+\boldsymbol{\epsilon}^{(k)})\odot\mathbf{x}_u^{(k)}+\sigma\left(\sum_{u,v\trianglelefteq e}\Lambda_{uv}\mathcal{F}_{u\trianglelefteq e}^{\top}\mathcal{F}_{v\trianglelefteq e}\mathbf{z}_v^{(k)}-\mathbf{z}_u^{(k)}\right). The messages and the aggregation are those of SheafAN. The term zu(k)=W1(k)xu(k)W2(k)\mathbf{z}_u^{(k)}=\mathbf{W}_1^{(k)}\mathbf{x}_u^{(k)}\mathbf{W}_2^{(k)} depends only on the state of uu, so it belongs to the node-local update φu(xu,mu)=(1+ϵ(k))⊙xu+σ(mu−W1(k)xuW2(k))\varphi_u(\mathbf{x}_u,\mathbf{m}_u)=(1+\boldsymbol{\epsilon}^{(k)})\odot\mathbf{x}_u+\sigma(\mathbf{m}_u-\mathbf{W}_1^{(k)}\mathbf{x}_u\mathbf{W}_2^{(k)}).

Proof of Theorem 1, part (iii): Sheaf Adjacency. Sheaf adjacency propagation (Bourgerie et al. [12]) replaces the Laplacian with the normalized sheaf adjacency A^F\hat{\mathbf{A}}_{\mathcal{F}}, whose (u,v)(u,v) block is Du−1/2Fu⊴eFv⊴eDv−1/2=F^u⊴e⊤F^v⊴e\mathbf{D}_{u}^{-1/2}\mathcal{F}_{u\trianglelefteq e}\mathcal{F}_{v\trianglelefteq e}\mathbf{D}_{v}^{-1/2}=\hat{\mathcal{F}}_{u\trianglelefteq e}^{\top}\hat{\mathcal{F}}_{v\trianglelefteq e}:

X(k+1)=(1+ϵ(k))⊙X(k)+ασ(A^F(k)Z(k))(12)\mathbf{X}^{(k+1)}=(1+\boldsymbol{\epsilon}^{(k)})\odot\mathbf{X}^{(k)}+\alpha\sigma\left(\hat{\mathbf{A}}_{\mathcal{F}(k)}\mathbf{Z}^{(k)}\right) \tag*{(12)}

At node uu the argument of σ\sigma is ∑u,v⊴eF^u⊴e⊤F^v⊴ezv(k)\sum_{u,v\trianglelefteq e}\hat{\mathcal{F}}_{u\trianglelefteq e}^{\top}\hat{\mathcal{F}}_{v\trianglelefteq e}\mathbf{z}_v^{(k)}. This is the blueprint with the normalized maps F^\hat{\mathcal{F}}, the message ψe(a,b)=a\psi_e(a,b)=a, sum aggregation, and the update φu(xu,mu)=(1+ϵ(k))⊙xu+ασ(mu)\varphi_u(\mathbf{x}_u,\mathbf{m}_u)=(1+\boldsymbol{\epsilon}^{(k)})\odot\mathbf{x}_u+\alpha\sigma(\mathbf{m}_u).

Proof of Theorem 1, part (iv): Neural Sheaf Propagation. Neural Sheaf Propagation (NSP) [53] follows the second-order recurrence:

X(k+1)=2X(k)−X(k−1)−σ(ΔF(k)Z(k)),X(−1)=0(13)\mathbf{X}^{(k+1)} = 2\mathbf{X}^{(k)} - \mathbf{X}^{(k-1)} - \sigma\left(\Delta_{\mathcal{F}^{(k)}}\mathbf{Z}^{(k)}\right), \qquad\mathbf{X}^{(-1)} = 0 \tag*{(13)}

with Z(k)\mathbf{Z}^{(k)} as in Equation (10). Because the update depends on X(k−1)\mathbf{X}^{(k-1)}, it is not directly of the form of Equation (5), where φu\varphi_u receives only the current state and the aggregated message. We remove this dependence by augmenting the state. Define x~u(k):=(xu(k),xu(k−1))∈R2d×f\widetilde{\mathbf{x}}_u^{(k)} := \left(\mathbf{x}_u^{(k)},\mathbf{x}_u^{(k-1)}\right) \in\mathbb{R}^{2d \times f}, with x~u(0)=(xu(0),0)\widetilde{\mathbf{x}}_u^{(0)} = \left(\mathbf{x}_u^{(0)},0\right), and let π1,π2\pi_1,\pi_2 project onto the current and history blocks. The augmented sheaf has node stalks R2d\mathbb{R}^{2d}, edge stalks Rd\mathbb{R}^d, and restriction maps F~u⊴e:=F^u⊴e∘π1:R2d→Rd\widetilde{F}_{u\trianglelefteq e} := \widehat{F}_{u\trianglelefteq e} \circ\pi_1 : \mathbb{R}^{2d} \to\mathbb{R}^d, which read the current block and apply the normalized original map. The transform uses W~1(k)=diag⁡(W1(k),0)\widetilde{W}_1^{(k)} = \operatorname{diag}\left(W_1^{(k)},0\right), so that z~u(k)=(zu(k),0)\widetilde{\mathbf{z}}_u^{(k)} = \left(\mathbf{z}_u^{(k)},0\right). With the message ψe(a,b)=b−a\psi_e(a,b)=b-a and sum aggregation:

mu(k+1)=∑u,v⊴eF~u⊴eT(F~u⊴ez~u(k)−F~v⊴ez~v(k))=([ΔF(k)Z(k)]u,0)\mathbf{m}_u^{(k+1)} = \sum_{u,v\trianglelefteq e} \widetilde{F}_{u\trianglelefteq e}^{\mathsf{T}}\left(\widetilde{F}_{u\trianglelefteq e}\widetilde{\mathbf{z}}_u^{(k)}-\widetilde{F}_{v\trianglelefteq e}\widetilde{\mathbf{z}}_v^{(k)}\right) = \left(\left[\Delta_{\mathcal{F}^{(k)}}\mathbf{Z}^{(k)}\right]_u,0\right)

by Equation (9), since F~u⊴eT=π1TF^u⊴eT\widetilde{F}_{u\trianglelefteq e}^{\mathsf{T}} = \pi_1^{\mathsf{T}}\widehat{F}_{u\trianglelefteq e}^{\mathsf{T}} embeds into the current block. The update then reads:

φu(x~u,mu)=(2π1(x~u)−π2(x~u)−σ(π1(mu)),π1(x~u))\varphi_u\left(\widetilde{\mathbf{x}}_u,\mathbf{m}_u\right) = \left(2\pi_1\left(\widetilde{\mathbf{x}}_u\right)-\pi_2\left(\widetilde{\mathbf{x}}_u\right)-\sigma\left(\pi_1\left(\mathbf{m}_u\right)\right),\pi_1\left(\widetilde{\mathbf{x}}_u\right)\right)

and it is a deterministic function of the augmented state and the aggregated message. By induction on kk, x~u(k)=(xu(k),xu(k−1))\widetilde{\mathbf{x}}_u^{(k)} = \left(\mathbf{x}_u^{(k)},\mathbf{x}_u^{(k-1)}\right) for all kk: the base case holds by the initialization, and if it holds at step kk, then π1(x~u(k+1))=2xu(k)−xu(k−1)−σ([ΔF(k)Z(k)]u)=xu(k+1)\pi_1\left(\widetilde{\mathbf{x}}_u^{(k+1)}\right) = 2\mathbf{x}_u^{(k)}-\mathbf{x}_u^{(k-1)}-\sigma\left(\left[\Delta_{\mathcal{F}^{(k)}}\mathbf{Z}^{(k)}\right]_u\right)=\mathbf{x}_u^{(k+1)} by Equation (13) and π2(x~u(k+1))=xu(k)\pi_2\left(\widetilde{\mathbf{x}}_u^{(k+1)}\right)=\mathbf{x}_u^{(k)}. The current block therefore reproduces NSP exactly. ■

Remark 3. The augmented restriction maps F~u⊴e:R2d→Rd\widetilde{F}_{u\trianglelefteq e}:\mathbb{R}^{2d}\to\mathbb{R}^d are not square, which the blueprint allows but which places NSP in a different sheaf regime from NSD, whose maps are endomorphisms. The degree of the augmented sheaf vanishes on the history block, so its own normalization is undefined; this is why the normalization of the original sheaf is folded into F~\widetilde{F}.

Remark 4 (Learnable Skip Rescaling). Any update that keeps a residual connection to the current state can be extended with learnable per-dimension rescalings, since these are constants shared by all nodes and leave φu\varphi_u a deterministic function of the state and the aggregated message. For NSP, the library’s add_eps option uses two rescalings ε1,ε2∈[−1,1]d\varepsilon_1,\varepsilon_2 \in[-1,1]^d, one for each block:

π1(x~u(k+1))=(2+ε1)⊙π1(x~u(k))−(1+ε2)⊙π2(x~u(k))−σ(π1(mu(k+1)))\pi_1\left(\widetilde{\mathbf{x}}_u^{(k+1)}\right) = (2+\varepsilon_1)\odot\pi_1\left(\widetilde{\mathbf{x}}_u^{(k)}\right) - (1+\varepsilon_2)\odot\pi_2\left(\widetilde{\mathbf{x}}_u^{(k)}\right) - \sigma\left(\pi_1\left(\mathbf{m}_u^{(k+1)}\right)\right)

which recovers Equation (13) at ε1=ε2=0\varepsilon_1=\varepsilon_2=0.

Polynomial Neural Sheaf Diffusion

Polynomial Neural Sheaf Diffusion (PolyNSD) [11] replaces the single Laplacian application of NSD with a degree-KK polynomial filter, evaluated through the Chebyshev recurrence without eigendecomposition. We show that a PolyNSD layer is a sequence of KK SheafMPNN steps followed by a node-wise readout.

Setting. The spectrum of ΔF\Delta_{\mathcal{F}} lies in [0,λmax⁡][0,\lambda_{\max}] with λmax⁡=2\lambda_{\max}=2 for the symmetric normalization. The rescaled Laplacian:

Δ^F:=2λmax⁡ΔF−Ind,spec⁡(Δ^F)⊆[−1,1](14)\widehat{\Delta}_{\mathcal{F}} := \frac{2}{\lambda_{\max}}\Delta_{\mathcal{F}}-\mathbf{I}_{nd}, \qquad\operatorname{spec}(\widehat{\Delta}_{\mathcal{F}})\subseteq[-1,1] \tag*{(14)}

maps the spectrum onto the interval on which the Chebyshev polynomials T0(x)=1T_0(x)=1, T1(x)=xT_1(x)=x, and Tk+1(x)=2xTk(x)−Tk−1(x)T_{k+1}(x)=2xT_k(x)-T_{k-1}(x) satisfy ∣Tk∣≤1|T_k|\leq1.

PolyNSD Update Rule. At layer ℓ\ell, let zu=W1(ℓ)xu(ℓ)W2(ℓ)\mathbf{z}_u=\mathbf{W}_1^{(\ell)}\mathbf{x}_u^{(\ell)}\mathbf{W}_2^{(\ell)} and define the Chebyshev iterates over the rescaled Laplacian:

T0=z,T1=Δ^Fz,Tk+1=2Δ^FTk−Tk−1(k≥1).(15)\mathbf{T}_0=\mathbf{z}, \qquad\mathbf{T}_1=\widehat{\Delta}_{\mathcal{F}}\mathbf{z}, \qquad\mathbf{T}_{k+1}=2\widehat{\Delta}_{\mathcal{F}}\mathbf{T}_k-\mathbf{T}_{k-1}\quad(k\geq1). \tag*{(15)}

The layer combines them with a high-pass skip term and a learnable convex combination:

hu=αhp(zu−1λmax⁡[ΔFz]u),(16)\mathbf{h}_u=\alpha_{\mathrm{hp}}\left(\mathbf{z}_u-\frac{1}{\lambda_{\max}}[\Delta_{\mathcal{F}}\mathbf{z}]_u\right), \tag*{(16)}
xu(ℓ+1)=diag⁡(γ)xu(ℓ)−σ(∑k=0Kθk[Tk]u+hu),(17)\mathbf{x}_u^{(\ell+1)}=\operatorname{diag}(\boldsymbol{\gamma})\mathbf{x}_u^{(\ell)}-\sigma\left(\sum_{k=0}^{K}\theta_k[\mathbf{T}_k]_u+\mathbf{h}_u\right), \tag*{(17)}

where θ=softmax⁡(θraw)\boldsymbol{\theta}=\operatorname{softmax}(\boldsymbol{\theta}_{\mathrm{raw}}), so that θk≥0\theta_k\geq0 and ∑kθk=1\sum_k\theta_k=1, γ=1+tanh⁡(ε)\boldsymbol{\gamma}=1+\tanh(\boldsymbol{\varepsilon}) with ε∈Rd\boldsymbol{\varepsilon}\in\mathbb{R}^d shared by all nodes, and αhp∈R\alpha_{\mathrm{hp}}\in\mathbb{R} is learnable. Since [ΔFz]u=λmax⁡2([T1]u+zu)[\Delta_{\mathcal{F}}\mathbf{z}]_u=\frac{\lambda_{\max}}{2}([\mathbf{T}_1]_u+\mathbf{z}_u), the skip term equals hu=αhp2([T0]u−[T1]u)\mathbf{h}_u=\frac{\alpha_{\mathrm{hp}}}{2}([\mathbf{T}_0]_u-[\mathbf{T}_1]_u) for any λmax⁡\lambda_{\max}, a combination of the first two iterates.

Definition 5 (Augmented PolyNSD State). For k∈{1,…,K}k\in\{1,\ldots,K\}, the augmented state of node uu is:

x~u(k):=([Tk]u,[Tk−1]u,Su(k))∈R3d×f,Su(k):=∑j=0kθj[Tj]u+hu(18)\widetilde{\mathbf{x}}_u^{(k)}:=([\mathbf{T}_k]_u,[\mathbf{T}_{k-1}]_u,\mathbf{S}_u^{(k)})\in\mathbb{R}^{3d\times f},\qquad\mathbf{S}_u^{(k)}:=\sum_{j=0}^{k}\theta_j[\mathbf{T}_j]_u+\mathbf{h}_u \tag*{(18)}

where the accumulator Su(k)\mathbf{S}_u^{(k)} already contains the skip term. The augmented sheaf F~\widetilde{\mathcal{F}} has node stalks R3d\mathbb{R}^{3d}, edge stalks Rd\mathbb{R}^{d}, and restriction maps F~u⊴e:=F^u⊴e∘π1:R3d→Rd\widetilde{\mathcal{F}}_{u\trianglelefteq e}:=\widehat{\mathcal{F}}_{u\trianglelefteq e}\circ\pi_1:\mathbb{R}^{3d}\to\mathbb{R}^{d}, where π1,π2,π3\pi_1,\pi_2,\pi_3 project onto the three blocks.

Theorem 6 (PolyNSD is a SheafMPNN). A PolyNSD layer of degree K≥1K\geq1 (Equation (17)) equals KK SheafMPNN steps on the augmented sheaf (G,F~)(G,\widetilde{\mathcal{F}}), which compute x~u(K)\widetilde{\mathbf{x}}_u^{(K)} from (zu,0,0)(\mathbf{z}_u,0,0), followed by the node-wise readout xu(ℓ+1)=diag⁡(γ)xu(ℓ)−σ(π3(x~u(K)))\mathbf{x}_u^{(\ell+1)}=\operatorname{diag}(\boldsymbol{\gamma})\mathbf{x}_u^{(\ell)}-\sigma(\pi_3(\widetilde{\mathbf{x}}_u^{(K)})). Every step uses identity weight matrices, the message ψe(a,b)=b−a\psi_e(a,b)=b-a, and sum aggregation; the steps differ only in their node-local updates.

Proof. Messages and Aggregation. At every step, the first block of the state holds the current iterate T\mathbf{T}. Since F~u⊴e\widetilde{\mathcal{F}}_{u\trianglelefteq e} reads only that block, Equation (9) gives the aggregated message:

mu=∑u,v⊴eF~u⊴eT(F~u⊴ex~u−F~v⊴ex~v)=([ΔFT]u,0,0)(19)\mathbf{m}_u=\sum_{u,v\trianglelefteq e}\widetilde{\mathcal{F}}_{u\trianglelefteq e}^{\mathsf{T}}\left(\widetilde{\mathcal{F}}_{u\trianglelefteq e}\widetilde{\mathbf{x}}_u-\widetilde{\mathcal{F}}_{v\trianglelefteq e}\widetilde{\mathbf{x}}_v\right)=\left([\Delta_{\mathcal{F}}\mathbf{T}]_u,0,0\right) \tag*{(19)}

one message per incidence and one propagation per step. The node can then form [Δ^FT]u=2λmax⁡π1(mu)−π1(x~u)[\widehat{\Delta}_{\mathcal{F}}\mathbf{T}]_u=\frac{2}{\lambda_{\max}}\pi_1(\mathbf{m}_u)-\pi_1(\widetilde{\mathbf{x}}_u) locally.

Updates. The first step maps (zu,0,0)(\mathbf{z}_u,0,0) to x~u(1)=([T1]u,zu,θ0zu+θ1[T1]u+αhp2(zu−[T1]u))\widetilde{\mathbf{x}}_u^{(1)}=([T_1]_u,\mathbf{z}_u,\theta_0\mathbf{z}_u+\theta_1[T_1]_u+\frac{\alpha_{\mathrm{hp}}}{2}(\mathbf{z}_u-[T_1]_u)) with [T1]u=[Δ^Fz]u[T_1]_u=[\widehat{\Delta}_{\mathcal{F}}\mathbf{z}]_u. Each later step k=1,…,K−1k=1,\ldots,K-1 applies the Chebyshev recurrence to the first two blocks and adds θk+1[Tk+1]u\theta_{k+1}[T_{k+1}]_u to the accumulator:

φu(x~u(k),mu)=(2[Δ^FTk]u−[Tk−1]u,[Tk]u,Su(k)+θk+1(2[Δ^FTk]u−[Tk−1]u)).(20)\varphi_u(\widetilde{\mathbf{x}}_u^{(k)},\mathbf{m}_u)=\left(2[\widehat{\Delta}_{\mathcal{F}}\mathbf{T}_k]_u-[T_{k-1}]_u,[T_k]_u,S_u^{(k)}+\theta_{k+1}\left(2[\widehat{\Delta}_{\mathcal{F}}\mathbf{T}_k]_u-[T_{k-1}]_u\right)\right). \tag*{(20)}

Both updates are deterministic functions of the current augmented state and the aggregated message, as Equation (5) requires.

Correctness. By Equation (15), the first component of Equation (20) is Tk+1\mathbf{T}_{k+1}, the second is Tk\mathbf{T}_k, and the third adds θk+1Tk+1\theta_{k+1}\mathbf{T}_{k+1} to the accumulator. Since Tk\mathbf{T}_k is generated by the Chebyshev recurrence in the matrix Δ^F\widehat{\Delta}_{\mathcal{F}}, induction gives Tk=Tk(Δ^F)z\mathbf{T}_k=T_k(\widehat{\Delta}_{\mathcal{F}})\mathbf{z}, and after KK steps π3(x~u(K))=∑k=0Kθk[Tk]u+hu\pi_3(\widetilde{\mathbf{x}}_u^{(K)})=\sum_{k=0}^{K}\theta_k[T_k]_u+\mathbf{h}_u, the argument of σ\sigma in Equation (17). The readout uses only xu\mathbf{x}_u and the state of uu, so it is node-wise and requires no further propagation. ■

Remark 7 (Reduction to NSD). For K=1K=1 and λmax⁡=2\lambda_{\max}=2, the argument of σ\sigma is (θ0−θ1+αhp)zu+(θ1−αhp2)[ΔFz]u(\theta_0-\theta_1+\alpha_{\mathrm{hp}})\mathbf{z}_u+(\theta_1-\frac{\alpha_{\mathrm{hp}}}{2})[\Delta_{\mathcal{F}}\mathbf{z}]_u. Choosing αhp=θ1−θ0\alpha_{\mathrm{hp}}=\theta_1-\theta_0 cancels the first term and leaves 12[ΔFz]u\frac{1}{2}[\Delta_{\mathcal{F}}\mathbf{z}]_u, because θ0+θ1=1\theta_0+\theta_1=1. Doubling W2(ℓ)\mathbf{W}_2^{(\ell)} absorbs the factor 12\frac{1}{2}, so the layer computes diag⁡(γ)xu−σ([ΔFz]u)\operatorname{diag}(\boldsymbol{\gamma})\mathbf{x}_u-\sigma([\Delta_{\mathcal{F}}\mathbf{z}]_u): the NSD update of Equation (10) with unit step size, which is the original update of Bodnar et al. [9]. Every such NSD layer is therefore a degree-one PolyNSD layer.

Remark 8 (Restriction-map Variants). The proof uses only the linearity of the restriction maps, so Theorem 6 holds for all six NSD map variants (Table 3). For orthogonal maps Fu⊴eFu⊴e=Id\mathcal{F}_{u\trianglelefteq e}\mathcal{F}_{u\trianglelefteq e}=\mathbf{I}_d, so Du=deg⁡(u)Id\mathbf{D}_u=\deg(u)\mathbf{I}_d and the normalization reduces to a scalar per node.

VariantRestriction parameterizationOutputs
DIAGONALdiag⁡(w)\operatorname{diag}(w), with w∈(−1,1)dw \in(-1,1)^{d}dd
GENERALDense matrix with entries in (−1,1)(-1,1)d2d^{2}
GENERAL_ATTENTIONI−softmax⁡(P)I-\operatorname{softmax}(P), with row-wise softmaxd2d^{2}
ORTHOGONALCayley or Householder construction(d2)\binom{d}{2} or d2d^{2}
ORTHOGONAL_ATTENTIONCayley transform of the skew part of I−softmax⁡(P)I-\operatorname{softmax}(P)d2d^{2}
LOW_RANKABTAB^{\mathsf{T}}, with A,B∈Rd×rA,B \in\mathbb{R}^{d \times r}2dr2dr

Table 3. NSD Restriction-map Variants. The last column gives the number of predictor outputs per restriction map, excluding fixed channels and edge weights. Low-rank maps need fewer outputs, but their products SueS_{ue} and CuveC_{uve} are still stored as dense d×dd \times d blocks.

Remark 9 (Laplacian-free Filter Evaluation). Each product Δ^FTk\widehat{\Delta}_{\mathcal{F}}\mathbf{T}_k is evaluated through Equation (19), which needs only the state of uu, the states of its neighbours, and the maps on its incidences, so the nd×ndnd\times nd operator is never assembled. Per layer, the library stores the restriction-map products, of total size O(∣E∣d2)O(|E|d^2), computed once by the map predictor and reused in all KK steps; the half-degree matrices Du−1/2\mathbf{D}_u^{-1/2}, of size O(nd2)O(nd^2); and three stalk tensors of size O(ndf)O(ndf), namely the two live iterates and the accumulator. A degree-KK layer therefore costs O(K∣E∣d2f)O(K|\mathcal{E}|d^2f) operations and O(∣E∣d2+nd2+ndf)O(|\mathcal{E}|d^2+nd^2+ndf) memory, excluding map prediction. By contrast, the original NSD implementation of Bodnar et al. [9] assembles a sparse nd×ndnd\times nd Laplacian with O(nd2+∣E∣d2)O(nd^2+|\mathcal{E}|d^2) non-zeros and multiplies it with the features, and spectral filters based on eigendecomposition additionally pay O((nd)3)O((nd)^3) for the factorization. Both message passing and sparse multiplication perform the same

O(∣E∣d2f)O(\lvert\mathcal{E}\rvert d^2 f) arithmetic per step; the difference lies in avoiding the assembly and storage of the global operator.

SheafPool as Graph-Level Sheaf Message Passing

SheafPool (Braithwaite et al. [14]) produces a graph-level representation from the node stalks of a sheaf backbone. We show that it is a single SheafMPNN layer in which every graph sends its aligned node stalks to a receive-only virtual node.

Setting. Let B={G1,…,GB}\mathcal{B} = \{\mathcal{G}_1,\ldots,\mathcal{G}_B\} be a batch of graphs, Gg=(Vg,Eg)\mathcal{G}_g = (\mathcal{V}_g,\mathcal{E}_g), and let Hi∈Rd×f\mathbf{H}_i \in\mathbb{R}^{d \times f} be the stalk embedding of node ii produced by the backbone. The pooling graph G+\mathcal{G}^{+} adds one virtual node ⋆g\star_g per graph and the arcs:

E+={(i→⋆g):i∈Vg, g=1,…,B}(21)\mathcal{E}^{+} = \{(i \to\star_g) : i \in\mathcal{V}_g,\ g = 1,\ldots,B\} \tag*{(21)}

and the pooling sheaf F+\mathcal{F}^{+} uses the stalk Rd\mathbb{R}^{d} at every node and edge, with identity restriction maps:

Fi⊴e=F⋆g⊴e=Idfor every arc e=(i→⋆g).(22)\mathcal{F}_{i\trianglelefteq e} = \mathcal{F}_{\star_g\trianglelefteq e} = \mathbf{I}_d \qquad\text{for every arc } e = (i \to\star_g). \tag*{(22)}

Messages are aggregated only along incoming arcs, as in the directed extension of Appendix § 5.0.2.§ 4, so the real nodes receive nothing and each virtual node is receive-only. Before pooling, SheafPool canonicalizes each node stalk. It whitens the stalk and aligns it to a learnable anchor A∈Rd×f\mathbf{A} \in\mathbb{R}^{d \times f} by orthogonal Procrustes:

Zi=(HiHiT+εId)−1/2Hi,Ri⋆=arg⁡min⁡R∈O(d)∥RTZi−A∥F2,Z~i=Ri⋆TZi(23)\mathbf{Z}_i = \left(\mathbf{H}_i\mathbf{H}_i^{\mathsf{T}} + \varepsilon\mathbf{I}_d\right)^{-1/2}\mathbf{H}_i,\qquad \mathbf{R}_i^{\star} = \underset{\mathbf{R}\in O(d)}{\arg\min}\left\|\mathbf{R}^{\mathsf{T}}\mathbf{Z}_i-\mathbf{A}\right\|_{F}^{2},\qquad \widetilde{\mathbf{Z}}_i = \mathbf{R}_i^{\star\mathsf{T}}\mathbf{Z}_i \tag*{(23)}

and scores it through the channel energies ui=diag⁡(Z~iTZ~i)∈Rf\mathbf{u}_i = \operatorname{diag}(\widetilde{\mathbf{Z}}_i^{\mathsf{T}}\widetilde{\mathbf{Z}}_i) \in\mathbb{R}^{f}, which are invariant under orthogonal changes of stalk basis:

αi=exp⁡(sθ(ui))∑j∈Vgexp⁡(sθ(uj)),i∈Vg.(24)\alpha_i = \frac{\exp(s_{\theta}(\mathbf{u}_i))}{\sum_{j\in\mathcal{V}_g}\exp(s_{\theta}(\mathbf{u}_j))},\qquad i\in\mathcal{V}_g. \tag*{(24)}

The pooled stalk, the update of a learnable graph token T∈Rd×f\mathbf{T} \in\mathbb{R}^{d \times f}, and the invariant readout are of the form:

Pg=∑i∈VgαiZ~i,(25)\mathbf{P}_g = \sum_{i\in\mathcal{V}_g}\alpha_i\widetilde{\mathbf{Z}}_i, \tag*{(25)}
T^g=LayerNorm⁡ϕ([T,Pg]),(26)\widehat{\mathbf{T}}_g = \operatorname{LayerNorm}_{\phi}([\mathbf{T},\mathbf{P}_g]), \tag*{(26)}
gg=ρ(T^g)=diag⁡(T^gTT^g)∈Rf(27)\mathbf{g}_g = \rho(\widehat{\mathbf{T}}_g) = \operatorname{diag}(\widehat{\mathbf{T}}_g^{\mathsf{T}}\widehat{\mathbf{T}}_g) \in\mathbb{R}^{f} \tag*{(27)}

where ϕ\phi is a channel-wise MLP. As Braithwaite et al. [14] stress, the token only receives information: it does not take part in the node-level diffusion and cannot act as a shortcut between nodes.

Proposition 10 (SheafPool is a Graph-level SheafMPNN). SheafPool is a single SheafMPNN layer on the pooling graph G+\mathcal{G}^{+} with the sheaf of Equation (22), followed by the node-wise readout ρ\rho at the virtual nodes.

Proof. The canonicalization in Equation (23) and the scores sθ(ui)s_\theta(\mathbf{u}_i) depend only on HiH_i, so they are node-local and can be computed by the update of the preceding layer; we take the pre-pooling state of node ii to be (Z~i,sθ(ui))(\widetilde{Z}_i,s_\theta(\mathbf{u}_i)). On each arc (i→⋆g)(i \to\star_g), the identity map transports Z~i\widetilde{Z}_i unchanged, and the message function sends the pair (exp⁡(sθ(ui))Z~i,exp⁡(sθ(ui)))(\exp(s_\theta(\mathbf{u}_i))\widetilde{Z}_i,\exp(s_\theta(\mathbf{u}_i))), which depends only on the source. Sum aggregation over the incoming arcs gives, at ⋆g\star_g, the pair (∑i∈Vgexp⁡(sθ(ui))Z~i,∑i∈Vgexp⁡(sθ(ui)))(\sum_{i\in V_g}\exp(s_\theta(\mathbf{u}_i))\widetilde{Z}_i,\sum_{i\in V_g}\exp(s_\theta(\mathbf{u}_i))). The update at ⋆g\star_g divides the first component by the second, which yields PgP_g of Equation (25) with the softmax weights of Equation (24), and then applies Equation (26). Real nodes have no incoming arcs and keep their states. Applying ρ\rho at each virtual node gives Equation (27). ■

Remark 11 The readout is permutation invariant when all node-wise choices are shared and deterministic. Invariance to general linear changes of stalk basis is not guaranteed by the regularized whitening: already for d=f=1d=f=1, H=hH=h gives h/h2+εh/\sqrt{h^2+\varepsilon}, whose magnitude changes under h↦ahh\mapsto ah, and exact unregularized whitening requires full row rank. Orthogonal invariance additionally requires a unique Procrustes solution or an equivariant tie-breaking rule, which arbitrary SVD choices at degeneracies do not provide. Proposition 10 therefore establishes locality, not unconditional gauge invariance.

Heterogeneous NSD and NSP as SheafMPNNs

Heterogeneous extensions of NSD and NSP [14] condition the restriction-map predictor on the type structure of the graph. Since the blueprint is parameterized by the restriction maps themselves and not by the mechanism that predicts them, any type-conditioned predictor yields a valid SheafMPNN.

Heterogeneous Graph Structure. Let G=(V,E)\mathcal{G}=(\mathcal{V},\mathcal{E}) be a graph with a node-type map τ:V→T\tau:\mathcal{V}\to\mathcal{T} and an edge-relation map ρ:E→R\rho:\mathcal{E}\to\mathcal{R} into finite sets of types. Every node and edge carries the stalk Rd\mathbb{R}^d.

Definition 12 (Type-conditioned Restriction-map Predictor).** A type-conditioned predictor at layer kk produces, for each incidence u⊴eu\unlhd e with e={u,v}e=\{u,v\}, a map Fu⊴e(k)=Φρ(e)(k)(c(k)(u,v,e))∈Rd×d\mathcal{F}^{(k)}_{u\unlhd e}=\Phi^{(k)}_{\rho(e)}(\mathbf{c}^{(k)}(u,v,e))\in\mathbb{R}^{d\times d}, where the context c(k)\mathbf{c}^{(k)} combines any non-empty subset of the node features [xu(k)∥xv(k)][\mathbf{x}^{(k)}_u\mathbin\Vert\mathbf{x}^{(k)}_v], the node-type one-hot encodings [1τ(u)∥1τ(v)][\mathbf{1}_{\tau(u)}\mathbin\Vert\mathbf{1}_{\tau(v)}], and the relation one-hot encoding 1ρ(e)\mathbf{1}_{\rho(e)}. The predictor is either a single MLP shared by all edges, which may receive the relation encoding as input, or an ensemble {Φr(k)}r∈R\{\Phi^{(k)}_r\}_{r\in\mathcal{R}} with one MLP per relation type. Its output parameterizes a diagonal, general, attention-based, orthogonal, or low-rank map as in the homogeneous case.

The type-conditioned Laplacian LFhetL_{\mathcal{F}_{\mathrm{het}}} and its normalization ΔFhet\Delta_{\mathcal{F}_{\mathrm{het}}} are defined as in the homogeneous case, with the type-conditioned maps in place of the original ones.

Het-NSD update rule. At layer kk, Het-NSD computes the next state xu(k+1)\mathbf{x}^{(k+1)}_u from the current state xu(k)\mathbf{x}^{(k)}_u and the normalized Laplacian of the transformed state zu(k)\mathbf{z}^{(k)}_u as:

xu(k+1)=xu(k)−α σ([ΔFhetz(k)]u),zu(k)=W1(k)xu(k)W2(k)(28)\mathbf{x}^{(k+1)}_u=\mathbf{x}^{(k)}_u-\alpha\,\sigma\left([\Delta_{\mathcal{F}_{\mathrm{het}}}\mathbf{z}^{(k)}]_u\right),\qquad \mathbf{z}^{(k)}_u=\mathbf{W}^{(k)}_1\mathbf{x}^{(k)}_u\mathbf{W}^{(k)}_2 \tag*{(28)}

with a learnable step size α\alpha and restriction maps from a type-conditioned predictor.

Theorem 13 (Het-NSD is a SheafMPNN). Het-NSD (Equation (28)) is a SheafMPNN on the type-conditioned sheaf (G,Fhet)(G,\mathcal{F}_{\mathrm{het}}), with the stalk transform zu(k)=W1(k)xu(k)W2(k)z_u^{(k)} = \mathbf{W}_1^{(k)}\mathbf{x}_u^{(k)}\mathbf{W}_2^{(k)}, the normalized maps F^u⊴e(k)=Fu⊴e(k)Du−1/2\widehat{\mathcal{F}}_{u\trianglelefteq e}^{(k)} = \mathcal{F}_{u\trianglelefteq e}^{(k)}\mathbf{D}_u^{-1/2}, the message ψe(a,b)=b−a\psi_e(a,b)=b-a, sum aggregation, and the update φu(xu,mu)=xu−α σ(mu)\varphi_u(\mathbf{x}_u,\mathbf{m}_u)=\mathbf{x}_u-\alpha\,\sigma(\mathbf{m}_u). Equivalently, after pullback, each edge contributes:

A^uu(k)zu(k)−A^uv(k)zv(k),A^uu(k)=F^u⊴e(k)TF^u⊴e(k),A^uv(k)=F^u⊴e(k)TF^v⊴e(k)(29)\widehat{\mathbf{A}}_{uu}^{(k)}\mathbf{z}_u^{(k)}-\widehat{\mathbf{A}}_{uv}^{(k)}\mathbf{z}_v^{(k)},\qquad\widehat{\mathbf{A}}_{uu}^{(k)}=\widehat{\mathcal{F}}_{u\trianglelefteq e}^{(k)\mathsf{T}}\widehat{\mathcal{F}}_{u\trianglelefteq e}^{(k)},\qquad\widehat{\mathbf{A}}_{uv}^{(k)}=\widehat{\mathcal{F}}_{u\trianglelefteq e}^{(k)\mathsf{T}}\widehat{\mathcal{F}}_{v\trianglelefteq e}^{(k)} \tag*{(29)}

which is how the library evaluates it from precomputed products.

Proof. By Equation (9) applied to the type-conditioned maps, we have:

[ΔFhet(k)z(k)]u=∑u,v⊴eF^u⊴e(k)T(F^u⊴e(k)zu(k)−F^v⊴e(k)zv(k))(30)\left[\Delta_{\mathcal{F}_{\mathrm{het}}}^{(k)}\mathbf{z}^{(k)}\right]_u=\sum_{u,v\trianglelefteq e}\widehat{\mathcal{F}}_{u\trianglelefteq e}^{(k)\mathsf{T}}\left(\widehat{\mathcal{F}}_{u\trianglelefteq e}^{(k)}\mathbf{z}_u^{(k)}-\widehat{\mathcal{F}}_{v\trianglelefteq e}^{(k)}\mathbf{z}_v^{(k)}\right) \tag*{(30)}

which is the message ψe(a,b)=b−a\psi_e(a,b)=b-a on the transported states, pulled back and summed; expanding the pullback gives Equation (29). The update xu−α σ(mu)\mathbf{x}_u-\alpha\,\sigma(\mathbf{m}_u) is a deterministic function of the state and the aggregated message. The argument uses only that each Fu⊴e(k)\mathcal{F}_{u\trianglelefteq e}^{(k)} is a linear map Rd→Rd\mathbb{R}^d\to\mathbb{R}^d, which Definition 12 guarantees for every context and map family. ■

Het-NSP Update Rule. Het-NSP keeps the second-order recurrence of NSP with type-conditioned maps:

xu(k+1)=2xu(k)−xu(k−1)−σ([ΔFhet(k)z(k)]u),xu(−1)=0(31)\mathbf{x}_u^{(k+1)}=2\mathbf{x}_u^{(k)}-\mathbf{x}_u^{(k-1)}-\sigma\left(\left[\Delta_{\mathcal{F}_{\mathrm{het}}}^{(k)}\mathbf{z}^{(k)}\right]_u\right),\qquad\mathbf{x}_u^{(-1)}=0 \tag*{(31)}

and stores the augmented state x~u(k)=(xu(k),xu(k−1))\widetilde{\mathbf{x}}_u^{(k)}=(\mathbf{x}_u^{(k)},\mathbf{x}_u^{(k-1)}) as a single tensor of shape [n,2d,f][n,2d,f].

Definition 14 (Augmented Het-NSP Sheaf). The augmented sheaf F~het\widetilde{\mathcal{F}}_{\mathrm{het}} has node stalks R2d\mathbb{R}^{2d}, edge stalks Rd\mathbb{R}^d, and restriction maps F~u⊴e(k):=F^u⊴e(k)∘π1:R2d→Rd\widetilde{\mathcal{F}}_{u\trianglelefteq e}^{(k)}:=\widehat{\mathcal{F}}_{u\trianglelefteq e}^{(k)}\circ\pi_1:\mathbb{R}^{2d}\to\mathbb{R}^d, where π1\pi_1 extracts the current block. The map predictor receives only the current block, so the history is never exposed to it.

Theorem 15 (Het-NSP is a SheafMPNN). Het-NSP (Equation (31)) is a SheafMPNN on the augmented sheaf (G,F~het)(G,\widetilde{\mathcal{F}}_{\mathrm{het}}), with the transform W~1=diag⁡(W1(k),0)\widetilde{\mathbf{W}}_1=\operatorname{diag}(\mathbf{W}_1^{(k)},0), the message ψe(a,b)=b−a\psi_e(a,b)=b-a, sum aggregation, and the update:

φu(x~u,mu)=(2π1(x~u)−π2(x~u)−σ(π1(mu)),π1(x~u)).(32)\varphi_u(\widetilde{\mathbf{x}}_u,\mathbf{m}_u)=\left(2\pi_1(\widetilde{\mathbf{x}}_u)-\pi_2(\widetilde{\mathbf{x}}_u)-\sigma\left(\pi_1(\mathbf{m}_u)\right),\pi_1(\widetilde{\mathbf{x}}_u)\right). \tag*{(32)}

Proof. The proof of Theorem 1, part (iv), applies verbatim with the type-conditioned maps: the aggregated message is ([ΔFhet(k)z(k)]u,0)\left([\Delta_{\mathcal{F}_{\mathrm{het}}}^{(k)}\mathbf{z}^{(k)}]_u,0\right) by Equation (30), and the same induction shows that the current block of Equation (32) reproduces Equation (31) while the second block stores the history. As for Het-NSD, only the linearity of the type-conditioned maps is used. ■

Remark 16 (Reduction to the Homogeneous Models). With a single node type and a single relation type, the context reduces to the node features and the ensemble to one

MLP, so the type-conditioned maps become the NSD maps of Bodnar et al. [9]. Het-NSD then coincides with NSD without skip rescaling (ε=0\varepsilon= 0 in Equation (10)), and Het-NSP with NSP.

Remark 17 (Type Conditioning preserves the Structure). All context strategies of Definition 12, and their combinations, produce restriction maps that are deterministic functions of the current node features and the graph structure. The theorems therefore hold for every map family and for every combination of the library options use_features, use_node_types, use_edge_types, and ensemble.

Remark 18 (Stalk Geometry of Het-NSP). As in Remark 3, the augmented maps are not square, and the degree of the augmented sheaf, ∑u⊴e(Fu⊴e(k)⊤Fu⊴e(k))⊕0∈R2d×2d\sum_{u\trianglelefteq e}\left(\mathcal{F}^{(k)\top}_{u\trianglelefteq e}\mathcal{F}^{(k)}_{u\trianglelefteq e}\right)\oplus0 \in\mathbb{R}^{2d\times2d}, vanishes on the history block. Only the current block takes part in the Laplacian action, and the normalization is taken from the original type-conditioned sheaf.

Directed Extension

For a directed edge e=(u→v)e=(u\to v), the source and target incidences may carry different predictors, Fu⊴e(k)=Φsrc(k)(xu∥xv)\mathcal{F}^{(k)}_{u\trianglelefteq e}=\Phi^{(k)}_{\mathrm{src}}(x_u\mathbin\Vert x_v) and Fv⊴e(k)=Φdst(k)(xu∥xv)\mathcal{F}^{(k)}_{v\trianglelefteq e}=\Phi^{(k)}_{\mathrm{dst}}(x_u\mathbin\Vert x_v), and both the predictors and the message function may depend on the order of the endpoints.

Theorem 19 (Directed SheafMPNN). Any directed sheaf layer whose messages are computed independently on each arc and whose node update aggregates the incoming messages with a permutation-invariant operator is an instance of the SheafMPNN blueprint, including layers with asymmetric source and target predictors and an asymmetric message function.

Proof. For each arc (v→u)(v\to u), set mv→u(k)=ψv→u(k)(Fv⊴e(k)zv(k),Fu⊴e(k)zu(k),euv)\mathbf{m}^{(k)}_{v\to u}=\psi^{(k)}_{v\to u}\left(\mathcal{F}^{(k)}_{v\trianglelefteq e}\mathbf{z}^{(k)}_v,\mathcal{F}^{(k)}_{u\trianglelefteq e}\mathbf{z}^{(k)}_u,e_{uv}\right). Pulling it back through Fu⊴e(k)⊤\mathcal{F}^{(k)\top}_{u\trianglelefteq e} and aggregating over the incoming arcs of uu gives Equation (4), and the node-local update gives Equation (5). Neither equation requires the maps, the messages, or the neighbourhood relation to be symmetric. ■\blacksquare

Cooperative Sheaf Neural Networks

Cooperative Sheaf Neural Networks (CSNNs) (Ribeiro et al., [48]) use directed cellular sheaves to separate sending from receiving. On a directed graph, their out- and in-degree sheaf Laplacians act as:

[LFoutx]u=∑v∈N+(u)(Fu⊴uv⊤Fu⊴uvxu−Fu⊴vu⊤Fv⊴vuxv)\left[L_{\mathcal{F}}^{\mathrm{out}}\mathbf{x}\right]_u=\sum_{v\in N^{+}(u)}\left(\mathcal{F}^{\top}_{u\trianglelefteq uv}\mathcal{F}_{u\trianglelefteq uv}\mathbf{x}_u-\mathcal{F}^{\top}_{u\trianglelefteq vu}\mathcal{F}_{v\trianglelefteq vu}\mathbf{x}_v\right)
[LFinx]u=∑v∈N−(u)(Fu⊴vu⊤Fu⊴vuxu−Fu⊴uv⊤Fv⊴uvxv)\left[L_{\mathcal{F}}^{\mathrm{in}}\mathbf{x}\right]_u=\sum_{v\in N^{-}(u)}\left(\mathcal{F}^{\top}_{u\trianglelefteq vu}\mathcal{F}_{u\trianglelefteq vu}\mathbf{x}_u-\mathcal{F}^{\top}_{u\trianglelefteq uv}\mathcal{F}_{v\trianglelefteq uv}\mathbf{x}_v\right)

and learned gates select and combine these directed transports locally.

Theorem 20 (Cooperative SNNs are SheafMPNNs). A CSNN layer built from LFoutL_{\mathcal{F}}^{\mathrm{out}} and LFinL_{\mathcal{F}}^{\mathrm{in}}, with arbitrary node-local gates and update, is a directed SheafMPNN.

Proof. Each summand of either Laplacian is a message on one directed incidence: the difference between a self transport and a neighbour transport, pulled back to the receiving stalk. Each operator is therefore realized by the message and sum-aggregation stages of Theorem 19. A gate computed from the state of a node and its aggregated messages can enter the weights ωuv\omega_{uv} or the update φu\varphi_u, and combining the two aggregated messages in that update is again a SheafMPNN layer. The independently parameterized in- and out-maps are what allow a node to control sending and receiving separately.

Joint Sheaf Neural Networks

Joint Sheaf Neural Networks (JSNNs) ([16]) infer the restriction maps through a joint diffusion process inspired by opinion dynamics, rather than through an unrestricted map learner. We model the map-generating process abstractly by an edge state ses_e, updated as se(k+1)=ge(k)(se(k),xu(k),xv(k))s_e^{(k+1)} = g_e^{(k)}(s_e^{(k)}, x_u^{(k)}, x_v^{(k)}), from which the maps are read as Fu⊴e(k)=Φu⊴e(k)(se(k))\mathcal{F}_{u\trianglelefteq e}^{(k)} = \Phi_{u\trianglelefteq e}^{(k)}(s_e^{(k)}).

Theorem 21 (JSNNs are SheafMPNNs). Every JSNN layer whose joint process yields linear incidence maps and whose feature update is sheaf diffusion is a SheafMPNN; if the joint process has memory, the result holds on the augmented state (xu,se)(x_u, s_e).

Proof. At a fixed layer, the state se(k)s_e^{(k)} determines linear maps Fu⊴e(k)\mathcal{F}_{u\trianglelefteq e}^{(k)}, and the feature update is the local transport, difference, pullback, and sum of part (i) of Theorem 1. The state update is edge-local and only determines the maps of the next layer, so it does not change this computation. When the state is recurrent, keeping ses_e as an auxiliary edge state gives an augmented local transition, as for NSP.

Bundle Neural Networks

Bundle Neural Networks (BuNNs) ([5]) diffuse features on a flat orthogonal vector bundle. In a local trivialization, each node carries an orthogonal frame Qu∈O(d)\mathbf{Q}_u \in\mathrm{O}(d), and parallel transport along {u,v}\{u,v\} is Pu←v=QuTQv\mathbf{P}_{u\leftarrow v} = \mathbf{Q}_u^{\mathsf{T}}\mathbf{Q}_v, which is path-independent by flatness.

Theorem 22 (BuNN Message Diffusion is a SheafMPNN). When the heat kernel is evaluated by a truncated Taylor series, a BuNN layer is a sequence of SheafMPNN steps on the flat orthogonal sheaf with restriction-map products Fu⊴eTFv⊴e=Pu←v\mathcal{F}_{u\trianglelefteq e}^{\mathsf{T}}\mathcal{F}_{v\trianglelefteq e} = \mathbf{P}_{u\leftarrow v}, followed by a node-wise update.

Proof. Choose the restriction maps in the frame of each edge so that their products equal Pu←v\mathbf{P}_{u\leftarrow v}; for instance, Fu⊴e=Qu\mathcal{F}_{u\trianglelefteq e} = \mathbf{Q}_u. The bundle Laplacian then acts at uu as ∑v∼u(zu−Pu←vzv)\sum_{v\sim u}(z_u-\mathbf{P}_{u\leftarrow v}z_v), which is the coboundary message of Equation (3), pulled back and summed as in Equation (4). The truncated Taylor series of the heat kernel is a polynomial in this Laplacian, so it is evaluated by repeated propagation with a running accumulator, exactly as in Theorem 6. Orthogonality and flatness restrict the map family and enable the factorization of BuNNs, but do not change the local form of the computation. The exact spectral evaluation of the heat kernel instead eigendecomposes the graph Laplacian and is not a local computation.

Bayesian Sheaf Neural Networks

Bayesian Sheaf Neural Networks (BSNNs) [30] treat the sheaf as a latent random variable with a learned variational distribution qϕ(F∣X,y)q_{\phi}(\mathcal{F}\mid\mathbf{X},y). At each layer, a sampled sheaf F(k)∼qϕ\mathcal{F}^{(k)}\sim q_{\phi} supplies the maps of an otherwise standard sheaf diffusion layer.

Theorem 23 (BSNNs are Conditionally SheafMPNNs). Conditional on every draw of its latent sheaf, a BSNN layer is a SheafMPNN, and its posterior-predictive output is the Monte Carlo average of these SheafMPNN evaluations.

Proof. Fix a draw F(k)\mathcal{F}^{(k)}. Its restriction maps are ordinary linear maps on the incidences, so part (i) of Theorem 1 applies verbatim. Reparameterized sampling changes how the maps are learned and how gradients are estimated, not the local computation once the maps are drawn. For SS draws, the posterior-predictive estimate S−1∑s=1SfFs(X)S^{-1}\sum_{s=1}^{S}f_{\mathcal{F}_{s}}(\mathbf{X}) averages the conditional SheafMPNN outputs, which amounts to a final permutation-invariant aggregation over samples.

Library Design and Usage: Additional Details

This appendix complements § 3. Sheaf-MPNN separates three concerns: predicting the restriction maps, propagating stalk-valued states by local message passing, and training models on specific tasks. We describe the package layout, the implemented model families, the anatomy of an NSD layer in terms of the blueprint of Equations (2)–(5), the end-to-end models, the experiment tooling, and the development workflow.

Package Layout

The source tree contains three packages (Table 1): sheaf_mpnn implements the homogeneous models and their convolutions, hetsheaf_mpnn their type-conditioned counterparts, and exp the data loading, model construction, training, and evaluation. Because the experiment code is kept apart, a convolution can be used in any PyTorch Geometric model without adopting the supplied training loop.

ModuleResponsibility
sheaf_mpnn.base_convShared stalk transforms, map-predictor inputs, and propagation interfaces.
sheaf_mpnn.<family>Architecture-specific convolutions and end-to-end models.
sheaf_mpnn.utilsNormalization, orthogonal parameterizations, connection maps, and training utilities.
sheaf_mpnn.sheaf_poolGraph-level pooling of stalk-valued representations.
hetsheaf_mpnnType-conditioned layers and model wrappers.
exp.config, exp.registriesTyped experiment settings and factories for models, datasets, and presets.
exp.run, exp.het_run, exp.gc_runRunners for homogeneous node classification, heterogeneous node classification, and graph classification.
exp.sweeps, exp.benchmarkHyperparameter search and benchmarks against reference implementations.

Table 1. Sheaf-MPNN Main Modules.

Each architecture family pairs a layer module, which defines propagation on stalk-valued states, with a model module, which adds the feature encoder and the prediction head. Most homogeneous convolutions derive from BaseSheafConv, itself a subclass of PyTorch Geometric’s MessagePassing. Directed convolutions derive from BaseDirectedSheafConv, and heterogeneous layers add type-aware restriction predictors. The base classes share the stalk transforms and common utilities, but leave each family free to define its own propagation rule.

Model Families and Restriction Maps

The model registry contains 15 homogeneous families, each with its heterogeneous counterpart, for 29 selectable model types (Table 2). Following Braithwaite et al. [14], the heterogeneous models condition their restriction-map predictors on type information (Appendix § 5.0.2.§ 3). Their registry keys prefix the homogeneous name with het_, except for polynomial diffusion, whose key is poly_het_nsd.

FamilyModel typeMap and model options
Neural Sheaf DiffusionnsdSix
Polynomial NSDpoly_nsdSix
Connection-Laplacian NSDconn_nsdPrecomputed maps
Deep NSDdnsdSix
Neural Sheaf PropagationnspSix
Sheaf adjacencysheaf_adjSix
Sheaf attentionsheaf_attnSheafAN, Res-SheafAN
Bayesian sheaf networksbsnnFour
Nonlinear sheaf diffusionnlsdFour
Bundle neural networksbunnTaylor or spectral solver
Directed NSDdirected_nsdSix
Cooperative sheaf networkscsnnConformal or non-conformal
Identity sheafid_sheafIdentity restrictions
Joint diffusionjoint_diffJoint update
Rotation-invariant sheafrot_invRotation-invariant update

Table 2. Homogeneous Architecture Families. The table lists the 15 homogeneous families and their corresponding model types and restriction-map options. In the last column, “six” denotes the six NSD restriction-map variants of Table 3, and “four” the diagonal, general, orthogonal, and low-rank maps.

NSD, PolyNSD, Deep NSD, NSP, sheaf adjacency, and directed NSD share the six restriction-map variants of NSD: diagonal, general, orthogonal, low-rank, general-attention, and orthogonal-attention (Appendix C.§ 3). The two attention variants change only how the maps are generated and are unrelated to the SheafAN and Res-SheafAN architectures. Bayesian and nonlinear diffusion support the four variants without attention; for nonlinear diffusion, the general and low-rank maps extend the diagonal and orthogonal maps of the reference model. The remaining families define their own parameterizations, such as the fixed maps of connection-Laplacian NSD, the flat bundle transports of BuNN, and the joint update of joint diffusion.

The directed families modify the propagation rule as well as the map predictor (Appendix § 5.0.2.§ 4). Also, every family propagates information through local messages and never assembles a global sheaf Laplacian. Only the optional spectral solver of BuNN departs from this, since it computes eigenpairs of the graph Laplacian with a full or truncated eigendecomposition, depending on the graph size and the configuration. The default BuNN solver stays local and evaluates a truncated Taylor expansion of the heat kernel instead (Appendix § 5.0.2.7).

Anatomy of an NSD Layer

An NSD convolution is called as layer(x_feat, x_stalk, edge_index). The tensor x_stalk holds the node states xu∈Rd×f\mathbf{x}_u \in\mathbb{R}^{d \times f} and has shape [n,d,f][n,d,f], while x_feat holds the context vectors from which the restriction maps are predicted and has shape [n,c][n,c], where cc is context_dim. The end-to-end model flattens the current state, so that c=dfc=df, but any context can be supplied. When the fixed channels of Table 4 are enabled, the stalk dimension grows to dtot=d+1add_lp+1add_hpd_{\mathrm{tot}} = d + 1_{\mathrm{add\_lp}} + 1_{\mathrm{add\_hp}}, which replaces dd in all tensor shapes.

OptionEffect
variant, rank, orth_strategySelect the restriction-map variant and its parameterization.
alpha, learn_alpha, add_epsSet the diffusion step and enable the learnable skip scaling.
use_edge_weightsEnable learned symmetric edge weights for orthogonal maps.
add_lp, add_hpAppend a fixed channel with signless (D+A)(D + A) or standard (D−A)(D - A) graph-Laplacian blocks, respectively.
sparse_learnerSum the paired contexts over the stalk axis, reducing the predictor width from 2dtotf2d_{\mathrm{tot}}f to 2f2f for flattened stalk inputs.
second_linearAdd a second encoder layer.
input_dropout, dropoutSet the input and internal dropout rates.
normalize_output, jknetNormalize the output representations, and concatenate the representations of all diffusion layers.
add_self_loopsInsert self-loops; off by default, since NuN_u already includes the identity term.

Table 4. Options of NSDModel beyond the core dimensions in_channels, out_channels, stalk_dim, hidden_dim, and num_layers.

Following PyTorch Geometric, an entry (v,u)(v,u) of edge_index sends a message from the source vv to the receiver uu, so an undirected graph must list both orientations of every edge. The predictor evaluates the two endpoint contexts in both orders to obtain the two restriction maps of each edge. It is a bias-free linear layer followed by tanh, except in the attention variants, which pass its output through a softmax-based construction (Table 3). The forward pass first applies the transform of Equation (2), zu=W1drop⁡(xu)W2z_u = W_1\operatorname{drop}(x_u)W_2, where dropout acts on the diffusion input but not on the residual state; at initialization, W1W_1 is the identity and W2W_2 a random orthogonal matrix. Instead of applying the restriction maps separately in every message, the layer precomputes the per-edge products:

Sue=Fu⊴eTFu⊴e,Cuve=Fu⊴eTFv⊴e.S_{ue} = \mathcal{F}_{u\trianglelefteq e}^{\mathsf{T}}\mathcal{F}_{u\trianglelefteq e}, \qquad C_{uve} = \mathcal{F}_{u\trianglelefteq e}^{\mathsf{T}}\mathcal{F}_{v\trianglelefteq e}.

With the block degree Du=∑e∋uSueD_u = \sum_{e\ni u} S_{ue} and Nu=(Du+I)−1/2N_u = (D_u + I)^{-1/2}, the pulled-back message of Equations (3)–(4), with ψe(a,b)=b−a\psi_e(a,b) = b-a and normalized maps Fu⊴eNu\mathcal{F}_{u\trianglelefteq e}N_u, becomes:

mv→u=NuSueNuzu−NuCuveNvzv.(33)m_{v\to u} = N_uS_{ue}N_u z_u - N_uC_{uve}N_v z_v . \tag*{(33)}

Summing these messages at uu yields the action of the augmented normalized sheaf Laplacian NLFNNL_{\mathcal{F}}N without forming the nd×ndnd \times nd operator, and the identity term keeps NuN_u well defined even when the restriction maps are singular. Two numerical safeguards, adapted from the reference implementation of Bodnar et al. [9], modify these products: for general and low-rank maps, the identity term receives a small jitter during training, and the normalized products of general maps are clipped entrywise to [−1,1][-1,1]. Equation (33) is therefore exact at evaluation time whenever the clipping is inactive.

With the default residual connection, the layer then instantiates Equation (5) as:

xunew=(1+tanh⁡(ε))⊙xu−α ELU⁡(∑v→umv→u)(34)x_u^{\mathrm{new}} = (1+\tanh(\varepsilon)) \odot x_u - \alpha\,\operatorname{ELU}\left(\sum_{v\to u}m_{v\to u}\right) \tag*{(34)}

where ϵ∈Rd\boldsymbol{\epsilon} \in\mathbb{R}^{d} is a learnable skip scaling, initialized at zero and broadcast across channels, and the step size α\alpha is learned by default in NSDModel. When the residual is disabled, the layer returns only the diffusion term −αELU⁡(⋅)-\alpha\operatorname{ELU}(\cdot), so that the caller can supply its own update.

The orthogonal class offers four strategies through orth_strategy. The cayley strategy uses a clamped half-Cayley transform, and fasth composes Householder reflections given by dd free reflector vectors. The fasthpp and householder strategies use compact reflector parameters; householder calls torch_householder when it is installed and otherwise falls back to a native implementation. For unweighted orthogonal maps, Sue=IS_{ue}=I and the normalization reduces to (deg⁡(u)+1)−1/2I(\deg(u)+1)^{-1/2}I; learned edge weights replace deg⁡(u)\deg(u) by a weighted degree. Connection-Laplacian NSD uses a separate convolution whose orthogonal transports are precomputed from local geometric estimates rather than learned.

End-to-End Models and Direct Layer Use

NSDModel applies input dropout, a linear encoder, an ELU, and dropout, and then reshapes the representation into stalks; an optional second encoder layer acts before the reshape. Each diffusion layer receives the current stalk state together with its flattened context, and from the second layer onwards the context also receives dropout. A linear decoder maps the final flattened state to the predictions, or the concatenation of all layer outputs when jumping knowledge is enabled. Table 4 lists the remaining options. The other families keep their own states and update rules, and hence their own options.

Convolutions can also be used on their own. In the following example, the caller supplies the encoder and the context, and no fixed channels are used:

from torch import nn
from sheaf_mpnn.nsd import GeneralNSDConv

d, f = 4, 16
encoder = nn.Linear(x.size(-1), d * f)
layer = GeneralNSDConv(stalk_dim=d, in_channels=f,
                       hidden_dim=f, context_dim=d * f)
x_stalk = encoder(x).reshape(-1, d, f)
x_feat = x_stalk.reshape(x_stalk.size(0), d * f)
x_stalk = layer(x_feat, x_stalk, edge_index)

Here x and edge_index are the node features and edges of the input graph. The hidden_dim argument is kept for interface compatibility and adds no hidden layer to the linear restriction predictor of NSD.

Experiment Tooling

The sheaf command provides four tools: run, splits, sweep, and benchmark. sheaf run trains homogeneous node-classification models, while heterogeneous node classification and graph classification have their own entry points, exp.het_run and exp.gc_run, which share the same configuration components:

sheaf run --preset texas --model.variant orthogonal --model.stalk-dim 5
sheaf splits --datasets cora texas
sheaf sweep --yaml-path configs/cora/nsd/general.yaml --preset cora_nsd_general
python -m exp.het_run --help
python -m exp.gc_run --help
sheaf benchmark report --manifest configs/benchmark/nsd_vs_original.yaml

Typed configurations describe the data, model, training procedure, hardware, and logging, and presets supply defaults that can be overridden from the command line. Training uses Adam, with a separate weight decay for the restriction-map predictors, and early stopping on a validation criterion. Results are summarized over the folds or seeds of each dataset’s split protocol; for example, the OGB node datasets have a single official split, whereas Pokec has five.

The homogeneous runner covers the citation and heterophily benchmarks, the filtered Chameleon and Squirrel graphs, the five datasets of Platonov et al. [47], the OGB node-property datasets, Pokec, Telegram, and a grid of synthetic directed graphs. Edges are symmetrized by default, and the --directed flag preserves the loaded orientation where one is available, so an experiment must state which of the two settings it uses. The heterogeneous runner supports the HGB datasets IMDB, DBLP, ACM, and Freebase, and the graph-classification runner supports the TU datasets with mean, sum, max, SAG, and SheafPool readouts. Data modules and a training module for link prediction are also included, although no runner exposes them yet.

Search spaces are stored as YAML files under configs/. The sweep tool uses the TPE sampler and median pruner of Optuna, supports shared study storage and optional Weights & Biases logging, and re-evaluates the best configuration over ten seeds or folds. Each file fixes its own search space and number of trials, so comparisons across models should report both.

The benchmark manifest configs/benchmark/nsd_vs_original.yaml compares diagonal, orthogonal, and general NSD with the original implementation of Bodnar et al. [9], which is included as a git submodule. The benchmark tool submits the runs as SLURM jobs, collects their outputs, and generates tables and plots of convergence, epoch time, peak GPU memory, and inference latency.

Development and Reproducibility

The environment is managed with uv and pins Python 3.13, PyTorch 2.8.0, and Lightning 2.6.0, with CUDA 12.8 wheels on Linux and Windows and CPU wheels on macOS. Linting and formatting use ruff, and type checking uses ty. GitHub Actions runs the unit tests with coverage on pushes and pull requests, the integration tests daily, and the benchmark integration tests weekly.

Ten tutorial notebooks accompany the code, from the basics of GNNs to the principal sheaf model families; two of them cover hypergraph and directed hypergraph sheaves, which are not yet registered model types. Reproducing an experiment requires the code version, environment, dataset and preprocessing, model and map variant, splits and seeds, tuning budget, and checkpoint-selection rule. Numerical comparisons with a reference implementation additionally require matched weights, normalization, random choices, and error tolerances. As noted in § 3, this paper reports neither test coverage nor numerical parity with reference implementations.

Acknowledgements

We thank Gabriele Onorato, Dario Loi, Ferran Hernandez Caralt, and James Rowbottom for their help in developing Sheaf-MPNN. Their contributions range from implementing and testing model families to preparing experiment configurations and maintaining the continuous-integration workflows, and we are grateful for their feedback and discussions throughout the project.

References

  1. [1]Takuya Akiba, Shotaro Sano, Toshihiko Yanase, Takeru Ohta, and Masanori Koyama. Optuna: A next-generation hyperparameter optimization framework. In Proceedings of the 25th ACM SIGKDD International Conference on Knowledge Discovery and Data Mining, 2019.
  2. [2]Riccardo Ali, Alessio Borgi, Mario Severino, Alessio Gravina, Davide Bacciu, Pietro Liò, and Christopher Irwin. Let the heads talk: Beyond diagonal graph attention, 2026. URL https://arxiv.org/abs/2610.01494.
  3. [3]Md Sadek Hossain Asif, Tanzila Khan, and Md. Mosaddek Khan. Temporal sheaf neural networks with dynamic orthogonal transport, 2026. URL https://arxiv.org/abs/2606. 10071.
  4. [4]Anton Ayzenberg, Thomas Gebhart, German Magai, and Grigory Solomadin. Sheaf theory: from deep geometry to deep learning, 2025. URL https://arxiv.org/abs/2502.15476.
  5. [5]Jacob Bamberger, Federico Barbero, Xiaowen Dong, and Michael M. Bronstein. Bundle neural network for message diffusion on graphs. In The Thirteenth International Conference on Learning Representations, 2025. URL https://openreview.net/forum?id=scI9307PLG.
  6. [6]Federico Barbero, Cristian Bodnar, Haitz Sáez de Ocáriz Borde, Michael Bronstein, Petar Veličković, and Pietro Liò. Sheaf Neural Networks with Connection Laplacians. In Proceedings of Topological, Algebraic, and Geometric Learning Workshops 2022, pages 28–36. PMLR, 2022a.arxiv.org/abs/2206.08702
  7. [7]Federico Barbero, Cristian Bodnar, Haitz Sáez de Ocáriz Borde, and Pietro Liò. Sheaf attention networks. In NeurIPS 2022 Workshop on Symmetry and Geometry in Neural Representations, 2022b. URL https://openreview.net/forum?id=LIDvgVJpkZr.
  8. [8]Claudio Battiloro, Zhiyang Wang, Hans Riess, Paolo Di Lorenzo, and Alejandro Ribeiro. Tangent bundle convolutional learning: From manifolds to cellular sheaves and back. IEEE Transactions on Signal Processing, 72:1892–1909, 2024. doi: 10.1109/TSP.2024.3379862.DOI
  9. [9]Cristian Bodnar, Francesco Di Giovanni, Benjamin Paul Chamberlain, Pietro Liò, and Michael M. Bronstein. Neural sheaf diffusion: A topological perspective on heterophily and oversmoothing in gnns. In Advances in Neural Information Processing Systems, 2022.
  10. [10]Alessio Borgi, Mario Severino, Fabrizio Silvestri, and Pietro Liò. Equivariant sheaf neural networks: Learning geometric transport on graphs, 2026a. URL https://arxiv.org/abs/ 2608.28853.arxiv.org/abs/2608.28853
  11. [11]Alessio Borgi, Fabrizio Silvestri, and Pietro Liò. Polynomial neural sheaf diffusion: A spectral filtering approach on cellular sheaves, 2026b. URL https://arxiv.org/abs/2512.00242.
  12. [12]Rémi Bourgerie, Šarūnas Girdzijauskas, and Viktoria Fodor. Deep neural sheaf diffusion. In ICML 2026 Workshop on Graph Foundation Models, 2026a. URL https://arxiv.org/ abs/2605.19021.arxiv.org/abs/2605.19021
  13. [13]Rémi Bourgerie, Šarūnas Girdzijauskas, and Viktoria Fodor. Fixed points without fixed diffusion: Implicit neural sheaves for convergent test-time computation. In Learning on Graphs Conference, 2026b. URL https://arxiv.org/abs/2609.30277.
  14. [14]Luke Braithwaite, Alessio Borgi, Gabriele Onorato, Kristjan Tarantelli, Iulia Duta, Francesco Restuccia, Fabrizio Silvestri, and Pietro Liò. Heterogeneous shear neural networks, 2026. URL https://arxiv.org/abs/2409.08036.
  15. [15]Chen Cai and Yusu Wang. A note on over-smoothing for graph neural networks. arXiv preprint arXiv:2006.13318, 2020.arxiv.org/abs/2006.13318
  16. [16]Ferran Hernandez Caralt, Guillermo Bernardez, Iulia Duta, Eduard Alarcon, and Pietro Liò. Joint diffusion processes as an inductive bias in shear neural networks. In ICML 2024 Workshop on Geometry-grounded Representation Learning and Generative Modeling, 2024. URL https://openreview.net/forum?id=0xkPQvpXIS.arxiv.org/abs/2407.20597
  17. [17]Ferran Hernandez Caralt, Mar González I Català, Adrián Bazaga, and Pietro Liò. On the necessity of learnable sheaf laplacians. In ICLR 2026 Workshop on Geometry-grounded Representation Learning and Generative Modeling, 2026. URL https://openreview.net/forum?id=IuXTYO5ggp.arxiv.org/abs/2603.05395
  18. [18]Seongjin Choi, Gahee Kim, and Yong-Geun Oh. Hypergraph neural sheaf diffusion: A symmetric simplicial set framework for higher-order learning. IEEE Access, 13:131823–131838, 2025.DOI
  19. [19]Yoonhyuk Choi, Jiho Choi, Taewook Ko, JongWook Kim, and Chong-Kwon Kim. Sheaf graph neural networks via pac-bayes spectral optimization. In Proceedings of the AAAI Conference on Artificial Intelligence, volume 40, pages 20570–20578, 2026.
  20. [20]John Cobb and Thomas Gebhart. Feature propagation on knowledge graphs using cellular sheaves, 2023. URL https://arxiv.org/abs/2309.03773.
  21. [21]Justin Michael Curry. Sheaves, Cosheaves and Applications. PhD thesis, University of Pennsylvania, 2014.arxiv.org/abs/1303.3255
  22. [22]Leonardo Di Nino, Sergio Barbarossa, and Paolo Di Lorenzo. Learning sheaf laplacian optimizing restriction maps. In 2024 58th Asilomar Conference on Signals, Systems, and Computers, pages 59–63, 2024. doi: 10.1109/IEEECONF60004.2024.10942997.DOI
  23. [23]Leonardo Di Nino, Gabriele D’Acunto, Sergio Barbarossa, and Paolo Di Lorenzo. Structured sheaf learning of consistent connection graphs, 2026. URL https://arxiv.org/abs/2608.08710.
  24. [24]Iulia Duta, Giulia Cassarà, Fabrizio Silvestri, and Pietro Lio. Sheaf Hypergraph Networks. In Thirty-seventh Conference on Neural Information Processing Systems, NeurIPS 2023, 2023a.arxiv.org/abs/2309.17116
  25. [25]Iulia Duta, Giulia Cassarà, Fabrizio Silvestri, and Pietro Lio. Sheaf hypergraph networks. In Thirty-seventh Conference on Neural Information Processing Systems, 2023b. URL https://openreview.net/forum?id=NVcXzJwhX.arxiv.org/abs/2309.17116
  26. [26]Matthias Fey, Jinu Sunil, Akihiro Nitta, Rishi Puri, Manan Shah, Blaž Stojanović, Ramona Bendias, Alexandria Barghi, Vid Kocijan, Zecheng Zhang, et al. Pyg 2.0: Scalable learning on real world graphs. arXiv preprint arXiv:2507.16991, 2025.arxiv.org/abs/2507.16991
  27. [27]Stefano Fiorini, Hakan Aktas, Iulia Duta, Pietro Morerio, Alessio Del Bue, Pietro Liò, and Stefano Coniglio. Sheaves reloaded: A direction awakening. In The Fourteenth International Conference on Learning Representations, 2026a. URL https://openreview.net/forum?id=iDiIETh7Qv.arxiv.org/abs/2506.02842
  28. [28]Stefano Fiorini, Edoardo Coppola, and Pietro Liò. Benchmarking sheaf neural networks for inductive tasks, 2026b. URL https://arxiv.org/abs/2608.02558.
  29. [29]Thomas Gebhart, Jakob Hansen, and Paul Schrater. Knowledge sheaves: A sheaf-theoretic framework for knowledge graph embedding. In Proceedings of the 26th International Conference on Artificial Intelligence and Statistics, volume 206 of Proceedings of Machine Learning Research, pages 9094–9116, 2023.
  30. [30]Patrick Gillespie, Layal Bou Hamdan, Ioannis Schizas, David L. Boothe, and Vasileios Maroulas. Bayesian sheaf neural networks. arXiv preprint arXiv:2410.09590, 2024.arxiv.org/abs/2410.09590
  31. [31]Justin Gilmer, Samuel S. Schoenholz, Patrick F. Riley, Oriol Vinyals, and George E. Dahl. Neural message passing for quantum chemistry. In Proceedings of the 34th International Conference on Machine Learning - Volume 70, ICML’17, page 1263–1272. JMLR.org, 2017.arxiv.org/abs/1704.01212
  32. [32]Francesco Maria Guadagnuolo, Alessio Borgi, Dorina Thanou, and Pietro Liò. A bochner weitzenböck decomposition for cellular sheaf laplacians, curvature and neural sheaf diffusion, 2026. URL https://arxiv.org/abs/2610.28455.
  33. [33]André Ribeiro Guimarães, Germano Barcelos, Amauri Souza, Diego Mesquita, and Ana Luiza Tenório. Mitigating over-squashing without rewiring: A sheaf effective resistance perspective. In The Fortieth Annual Conference on Neural Information Processing Systems, 2026.
  34. [34]Mustafa Hajij, Mathilde Papillon, Florian Frantzen, Jens Agerberg, Ibrahem AlJabea, Rubén Ballester, Claudio Battiloro, Guillermo Bernárdez, Tolga Birdal, Aiden Brent, et al. TopoX: A suite of Python packages for machine learning on topological domains. Journal of Machine Learning Research, 25(374):1–8, 2024.arxiv.org/abs/2402.02441
  35. [35]Mustafa Hajij, Lennart Bastian, Sarah Osentoski, Hardik Kabaria, John L. Davenport, Sheik Dawood, Balaji Cherukuri, Joseph G. Kocheemoolayil, Nastaran Shahmansouri, Adrian Lew, Theodore Papamarkou, and Tolga Birdal. Copresheaf topological neural networks: A generalized deep learning framework. In The Thirty-ninth Annual Conference on Neural Information Processing Systems, 2025. URL https://openreview.net/forum?id=3G56xC1PYg.arxiv.org/abs/2505.21251
  36. [36]Jakob Hansen and Thomas Gebhart. Sheaf neural networks. In NeurIPS Workshop on TDA & Beyond, 2020. URL https://openreview.net/forum?id=GgcgIJsT8HD.arxiv.org/abs/2012.06333
  37. [37]Jakob Hansen and Robert Ghrist. Learning sheaf laplacians from smooth signals. In ICASSP 2019 - 2019 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP), pages 5446–5450, 2019a. doi: 10.1109/ICASSP.2019.8683709.DOI
  38. [38]Jakob Hansen and Robert Ghrist. Toward a spectral theory of cellular sheaves. Journal of Applied and Computational Topology, 3(4):315–358, 2019b.DOI
  39. [39]Jakob Hansen and Robert Ghrist. Opinion dynamics on discourse sheaves. SIAM Journal on Applied Mathematics, 81(5):2033–2060, 2021.arxiv.org/abs/2005.12798
  40. [42]Kotaro Kamiya and Joel Nicholls. Clifford sheaf neural networks, 2026. URL https://arxiv.org/abs/2610.01322.
  41. [43]Emanuele Mule, Stefano Fiorini, Antonio Purificato, Federico Siciliano, Stefano Coniglio, and Fabrizio Silvestri. Directional sheaf hypergraph networks: Unifying learning on directed and undirected hypergraphs. In The Fourteenth International Conference on Learning Representations, 2026. URL https://openreview.net/forum?id=d1hQkcDy7c.
  42. [44]Dionisia Naddeo, Carlo Abate, Pietro Liò, Nicola Toschi, and Filippo Maria Bianchi. Hierarchical pooling for sheaf neural networks, 2026. URL https://arxiv.org/abs/2606.20932.
  43. [45]Adam Paszke, Sam Gross, Francisco Massa, Adam Lerer, James Bradbury, Gregory Chanan, Trevor Killeen, Zeming Lin, Natalia Gimelshein, Luca Antiga, Alban Desmaison, Andreas Köp, Edward Yang, Zachary DeVito, Martin Raison, Aly Khan Tejani, Sasank Chilamkurthy, Benoit Steiner, Lu Fang, Junjie Bai, and Soumith Chintala. PyTorch: An imperative style, high-performance deep learning library. In Advances in Neural Information Processing Systems, volume 32, 2019.arxiv.org/abs/1912.01703
  44. [46]Yuhan Peng, Junwen Dong, Yuzhi Zeng, Hao Li, Ce Ju, Huitao Feng, Diaaeldin Taha, Anna Wienhard, and Kelin Xia. Sheaf neural networks on spd manifolds: Second-order geometric representation learning, 2026. URL https://arxiv.org/abs/2604.20308.
  45. [47]Oleg Platonov, Denis Kuznedelev, Michael Diskin, Artem Babenko, and Liudmila Prokhorenkova. A critical look at the evaluation of GNNs under heterophily: Are we really making progress? In The Eleventh International Conference on Learning Representations, 2023. URL https://openreview.net/forum?id=JbQbQfW-5wv.arxiv.org/abs/2302.11640
  46. [48]André Ribeiro, Ana Luiza Tenorio, Juan Belieni, Amauri H. Souza, and Diego Mesquita. Co-operative sheaf neural networks. In International Conference on Learning Representations, 2026a.
  47. [49]André Ribeiro, Ana Luiza Tenório, Tiago da Silva, and Diego Mesquita. Gaussian sheaf neural networks, 2026b. URL https://arxiv.org/abs/2605.21435.
  48. [50]Daniel Rosiak. Sheaf Theory through Examples. The MIT Press, 10 2022. ISBN 9780262370424. doi: 10.7551/mitpress/12581.001.0001. URL https://doi.org/10.7551/mitpress/12581.001.0001.
  49. [51]T Konstantin Rusch, Michael M Bronstein, and Siddhartha Mishra. A survey on oversmoothing in graph neural networks. arXiv preprint arXiv:2303.10993, 2023.arxiv.org/abs/2303.10993
  50. [52]Allen D. Shepard. A Cellular Description of the Derived Category of a Stratified Space. PhD thesis, Brown University, 1985.
  51. [53]Julian Suk, Lorenzo Giusti, Tamir Hemo, Miguel Lopez, Konstantinos Barmpas, and Cristian Bodnar. Surfing on the neural sheaf. In NeurIPS 2022 Workshop on Symmetry and Geometry in Neural Representations, 2022. URL https://openreview.net/forum?id=xOXFkyRzTIu.
  52. [54]Jan-Willem Van Looy, Alessandro Trenta, Alessio Gravina, Alessio Borgi, Ferdinando Zanchetta, Pietro Liò, David Bacciu, and Rita Fioriesi. Oscillatory neural dynamics over sheaves, 2026. URL https://arxiv.org/abs/2610.10018.
  53. [55]Minjie Wang, Da Zheng, Zihao Ye, Quan Gan, Mufei Li, Xiang Song, Jinjing Zhou, Chao Ma, Lingfan Yu, Yu Gai, Tianjun Xiao, Tong He, George Karypis, Jinyang Li, and Zheng Zhang. Deep graph library: A graph-centric, highly-performant package for graph neural networks, 2019.
  54. [56]Olga Zaghen, Antonio Longa, Steve Azzolin, Lev Telyatnikov, Andrea Passerini, and Pietro Liò. Sheaf diffusion goes nonlinear: Enhancing GNNs with adaptive sheaf laplacians. In ICML 2024 Workshop on Geometry-grounded Representation Learning and Generative Modeling, 2024. URL https://openreview.net/forum?id=MGQtGV5gPO.

Paper details

vlnc:W_vckcrakh
Version
v2 · latest
Published
Fresh — added to the Hub within the last 30 days
Added
License
CC BY 4.0
Usage

views · 1

downloads · 0

A view counts once per browser per day, a download each time the PDF is requested.

  • Computer Science

Not recorded for this paper

View statement
Looking for related papers…
Contents