pyg-nightly 2.7.0.dev20250603__py3-none-any.whl → 2.7.0.dev20250604__py3-none-any.whl

{pyg_nightly-2.7.0.dev20250603.dist-info → pyg_nightly-2.7.0.dev20250604.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyg-nightly
-Version: 2.7.0.dev20250603
+Version: 2.7.0.dev20250604
 Summary: Graph Neural Network Library for PyTorch
 Keywords: deep-learning,pytorch,geometric-deep-learning,graph-neural-networks,graph-convolutional-networks
 Author-email: Matthias Fey <matthias@pyg.org>

{pyg_nightly-2.7.0.dev20250603.dist-info → pyg_nightly-2.7.0.dev20250604.dist-info}/RECORD

@@ -1,4 +1,4 @@
-torch_geometric/__init__.py,sha256=a6RvMmtC3cM-AdkArSXekU2E4-8E99MWvpJfWEZ_1io,2255
+torch_geometric/__init__.py,sha256=di4kZd7rQFDpBlATSXKDIp6hVI7yFbo5CFhhBq2M5zs,2255
 torch_geometric/_compile.py,sha256=f-WQeH4VLi5Hn9lrgztFUCSrN_FImjhQa6BxFzcYC38,1338
 torch_geometric/_onnx.py,sha256=V9ffrIKSqhDw6xUZ12lkuSfNs48cQp2EeJ6Z19GfnVw,349
 torch_geometric/backend.py,sha256=lVaf7aLoVaB3M-UcByUJ1G4T4FOK6LXAg0CF4W3E8jo,1575
@@ -71,7 +71,7 @@ torch_geometric/datasets/ba_shapes.py,sha256=sJEQiK3CGlYTdbQBgKeLhO6mY-HRv3nS9Ya
 torch_geometric/datasets/bitcoin_otc.py,sha256=olrsq_Z306-oo17iEQoVif3-CgVIOyVc8twgIMXE0iI,4399
 torch_geometric/datasets/brca_tgca.py,sha256=2lX9oY6T7aPut8NbXFMWS1c2-_FHqCB4hqUzP4_zFsk,3962
 torch_geometric/datasets/citation_full.py,sha256=5WT6_iZ1GWuShuYZJErQ3bWNV4bHwZsYYBYztoTxMzs,4458
-torch_geometric/datasets/city.py,sha256=9EFbPDFlEweVYvZL9V4jmuY_wioKTcax0YxeisZbis4,5138
+torch_geometric/datasets/city.py,sha256=RgOokL8CD1dU4hN_VFzCdUmom57FPwmZjUoulY5X8tM,5190
 torch_geometric/datasets/coauthor.py,sha256=Nma9aLapDE1S7lCC40WazQZbBJ8nMQV3JJZRci-F3XQ,3138
 torch_geometric/datasets/coma.py,sha256=4URaPuXdUJdtZbzWojR-BqxlTyykjtvmXptk3G2Uy9k,4734
 torch_geometric/datasets/cornell.py,sha256=i6wUr2m1U3HCaqMzi-0AZ3Nthdne6_t0ja8qCKYESzE,5311
@@ -337,7 +337,7 @@ torch_geometric/nn/attention/__init__.py,sha256=wLKTmlfP7qL9sZHy4cmDFHEtdwa-MEKE
 torch_geometric/nn/attention/performer.py,sha256=2PCDn4_-oNTao2-DkXIaoi18anP01OxRELF2pvp-jk8,7357
 torch_geometric/nn/attention/qformer.py,sha256=7J-pWm_vpumK38IC-iCBz4oqL-BEIofEIxJ0wfjWq9A,2338
 torch_geometric/nn/attention/sgformer.py,sha256=OBC5HQxbY289bPDtwN8UbPH46To2GRTeVN-najogD-o,3747
-torch_geometric/nn/conv/__init__.py,sha256=37zTdt0gfSAUPMtwXjZg5mWx_itojJVFNODYR1h1ch0,3515
+torch_geometric/nn/conv/__init__.py,sha256=8CK-DFG2PEo2ZaFyg-IUlQH8ecQoDDi556uv3ugeQyc,3572
 torch_geometric/nn/conv/agnn_conv.py,sha256=5nEPLx_BBHcDaO6HWzLuHfXc0Yd_reKynAOH0Iq09lU,3077
 torch_geometric/nn/conv/antisymmetric_conv.py,sha256=dhA6sCETy1jlXReYJZBSyToOcL_mZ1wL10fMIb8Ppuw,4387
 torch_geometric/nn/conv/appnp.py,sha256=5hleE5c51Xq0nSP_PyRbr-ukM-3KRROdLrSNhc4AOX0,5983
@@ -374,6 +374,7 @@ torch_geometric/nn/conv/hgt_conv.py,sha256=lUhTWUMovMtn9yR_b2-kLNLqHChGOUl2OtXBY
 torch_geometric/nn/conv/hypergraph_conv.py,sha256=4BosbbqJyprlI6QjPqIfMxCqnARU_0mUn1zcAQhbw90,8691
 torch_geometric/nn/conv/le_conv.py,sha256=DonmmYZOKk5wIlTZzzIfNKqBY6MO0MRxYhyr0YtNz-Q,3494
 torch_geometric/nn/conv/lg_conv.py,sha256=8jMa79iPsOUbXEfBIc3wmbvAD8T3d1j37LeIFTX3Yag,2369
+torch_geometric/nn/conv/meshcnn_conv.py,sha256=hQpqpOl_pHQA-48tX9E_EDipWcHW2tupI7uiFJfxyHU,22209
 torch_geometric/nn/conv/message_passing.py,sha256=ynTp5MlvHB4SFYnuetK4wWi_1Bj_FhDGAJbf6ZmhEqY,44360
 torch_geometric/nn/conv/mf_conv.py,sha256=SkOGMN1tFT9dcqy8xYowsB2ozw6QfkoArgR1BksZZaU,4340
 torch_geometric/nn/conv/mixhop_conv.py,sha256=qVDPWeWcnO7_eHM0ZnpKtr8SISjb4jp0xjgpoDrwjlk,4555
@@ -586,7 +587,7 @@ torch_geometric/transforms/to_superpixels.py,sha256=g8ysBv-ezcHn2gHucKuBtnbe-kBD
 torch_geometric/transforms/to_undirected.py,sha256=oklgrNzev7HjvVaBHwPQFo0RxcQpmcIebNbcv6vNCtY,2972
 torch_geometric/transforms/two_hop.py,sha256=XxZl3eztTjE00ZlyAIqYu36rjaRddQT-1v4AFF9VUBc,1313
 torch_geometric/transforms/virtual_node.py,sha256=FMGT6LZBH-SU2zmp76GKNqJBZ8PyS1_6Em2BbVhv8Tw,2932
-torch_geometric/utils/__init__.py,sha256=aVet2bjRvr3URikJ6LpjLATz447YuBS6FuSu5l3JwLY,4982
+torch_geometric/utils/__init__.py,sha256=VkLBKLR_ArzMj2PeZuUXPzE6xoa13lUKNd5LH3RXWgU,5044
 torch_geometric/utils/_assortativity.py,sha256=pe2Hv5xLWhTW7dgqVWNiwDgDVMxMbliTdLeQf5Y65Ug,2347
 torch_geometric/utils/_coalesce.py,sha256=m4s_maBhib0jByQi6Cd8dazzhFVshZXLfB9aykCZT2g,6769
 torch_geometric/utils/_degree.py,sha256=FcsGx5cQdrBmoCQ4qQ2csjsTiDICP1as4x1HD9y5XVk,1017
@@ -619,6 +620,7 @@ torch_geometric/utils/embedding.py,sha256=b-CQ-aapEgahxSS7fuL4aNQX6GJROboV0xclZ_
 torch_geometric/utils/functions.py,sha256=orQdS_6EpzWSmBHSok3WhxCzLy9neB-cin1aTnlXY-8,703
 torch_geometric/utils/geodesic.py,sha256=-xsqE3FZU7Y9gMbucIlGJ4FM-3nk8o0AQBxIdN-QfEw,4770
 torch_geometric/utils/hetero.py,sha256=ok4uAAOyMiaeEPmvyS4DNoDwdKnLS2gmgs5WVVklxOo,5539
+torch_geometric/utils/influence.py,sha256=b2v4G2jA-FKWWSohIc4iNkyFgUvS6j_g97qWT6xfrzI,9920
 torch_geometric/utils/isolated.py,sha256=nUxCfMY3q9IIFjelr4eyAJH4sYG9W3lGdpWidnp3dm4,3588
 torch_geometric/utils/laplacian.py,sha256=ludDil4yS1A27PEuYOjZtCtE3o-t0lnucJKfiqENhvM,3695
 torch_geometric/utils/loop.py,sha256=MUWUS7a5GxuxLKlCtRq95U1hc3MndybAhqKD5IAe2RY,23051
@@ -638,7 +640,7 @@ torch_geometric/utils/undirected.py,sha256=H_nfpI0_WluOG6VfjPyldvcjL4w5USAKWu2x5
 torch_geometric/visualization/__init__.py,sha256=b-HnVesXjyJ_L1N-DnjiRiRVf7lhwKaBQF_2i5YMVSU,208
 torch_geometric/visualization/graph.py,sha256=mfZHXYfiU-CWMtfawYc80IxVwVmtK9hbIkSKhM_j7oI,14311
 torch_geometric/visualization/influence.py,sha256=CWMvuNA_Nf1sfbJmQgn58yS4OFpeKXeZPe7kEuvkUBw,477
-pyg_nightly-2.7.0.dev20250603.dist-info/licenses/LICENSE,sha256=ic-27cMJc1kWoMEYncz3Ya3Ur2Bi3bNLWib2DT763-o,1067
-pyg_nightly-2.7.0.dev20250603.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-pyg_nightly-2.7.0.dev20250603.dist-info/METADATA,sha256=k8073M3Yw3Yrrcqz1VGFnEmGZu-clDXcl5GIdqvh2B8,62967
-pyg_nightly-2.7.0.dev20250603.dist-info/RECORD,,
+pyg_nightly-2.7.0.dev20250604.dist-info/licenses/LICENSE,sha256=ic-27cMJc1kWoMEYncz3Ya3Ur2Bi3bNLWib2DT763-o,1067
+pyg_nightly-2.7.0.dev20250604.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+pyg_nightly-2.7.0.dev20250604.dist-info/METADATA,sha256=pOkfyi_H6pwQ7MLQrQ2nbMuuzDu7C1CLo_GNz0l-NsM,62967
+pyg_nightly-2.7.0.dev20250604.dist-info/RECORD,,

torch_geometric/__init__.py

@@ -31,7 +31,7 @@ from .lazy_loader import LazyLoader
 contrib = LazyLoader('contrib', globals(), 'torch_geometric.contrib')
 graphgym = LazyLoader('graphgym', globals(), 'torch_geometric.graphgym')
 
-__version__ = '2.7.0.dev20250603'
+__version__ = '2.7.0.dev20250604'
 
 __all__ = [
     'Index',

torch_geometric/datasets/city.py

@@ -16,11 +16,12 @@ class CityNetwork(InMemoryDataset):
     a Large Graph Dataset and a Measurement"
     <https://arxiv.org/abs/2503.09008>`_ paper.
     The dataset contains four city networks: `paris`, `shanghai`, `la`,
-    and 'london', where nodes represent junctions and edges represent
-    directed road segments. The task is to predict each node's eccentricity
-    score, which is approximated based on its 16-hop neighborhood. The score
-    indicates how accessible one node is in the network, and is mapped to
-    10 quantiles for transductive classification. See the original
+    and `london`, where nodes represent junctions and edges represent
+    undirected road segments. The task is to predict each node's eccentricity
+    score, which is approximated based on its 16-hop neighborhood and naturally
+    requires long-range information. The score indicates how accessible one
+    node is in the network, and is mapped to 10 quantiles for transductive
+    classification. See the original
     `source code <https://github.com/LeonResearch/City-Networks>`_ for more
     details on the individual networks.
 

torch_geometric/nn/conv/__init__.py

@@ -61,6 +61,7 @@ from .gps_conv import GPSConv
 from .antisymmetric_conv import AntiSymmetricConv
 from .dir_gnn_conv import DirGNNConv
 from .mixhop_conv import MixHopConv
+from .meshcnn_conv import MeshCNNConv
 
 import torch_geometric.nn.conv.utils  # noqa
 
@@ -131,6 +132,7 @@ __all__ = [
     'AntiSymmetricConv',
     'DirGNNConv',
     'MixHopConv',
+    'MeshCNNConv',
 ]
 
 classes = __all__

torch_geometric/nn/conv/meshcnn_conv.py

@@ -0,0 +1,491 @@
+# The below is to suppress the warning on torch.nn.conv.MeshCNNConv::update
+# pyright: reportIncompatibleMethodOverride=false
+from typing import Optional
+from warnings import warn
+
+import torch
+from torch.nn import Linear, Module, ModuleList
+
+from torch_geometric.nn.conv import MessagePassing
+from torch_geometric.typing import Tensor
+
+
+class MeshCNNConv(MessagePassing):
+    r"""The convolutional layer introduced by the paper
+    `"MeshCNN: A Network With An Edge" <https://arxiv.org/abs/1809.05910>`_.
+
+    Recall that, given a set of categories :math:`C`,
+    MeshCNN is a function that takes as its input
+    a triangular mesh
+    :math:`\mathcal{m} = (V, F) \in \mathbb{R}^{|V| \times 3} \times
+    \{0,...,|V|-1\}^{3 \times |F|}`, and returns as its output
+    a :math:`|C|`-dimensional vector, whose :math:`i` th component denotes
+    the probability of the input mesh belonging to category :math:`c_i \in C`.
+
+    Let :math:`X^{(k)} \in \mathbb{R}^{|E| \times \text{Dim-Out}(k)}`
+    denote the output value of the prior (e.g. :math:`k` th )
+    layer of our neural network. The :math:`i` th row of :math:`X^{(k)}` is a
+    :math:`\text{Dim-Out}(k)`-dimensional vector that represents the features
+    computed by the :math:`k` th layer for edge :math:`e_i` of the input mesh
+    :math:`\mathcal{m}`. Let :math:`A \in \{0, ..., |E|-1\}^{2 \times 4*|E|}`
+    denote the *edge adjacency* matrix of our input mesh :math:`\mathcal{m}`.
+    The :math:`j` th column of :math:`A` returns a pair of indices
+    :math:`k,l \in \{0,...,|E|-1\}`, which means that edge
+    :math:`e_k` is adjacent to edge :math:`e_l`
+    in our input mesh :math:`\mathcal{m}`.
+    The definition of edge adjacency in a triangular
+    mesh is illustrated in Figure 1.
+    In a triangular
+    mesh, each edge :math:`e_i` is expected to be adjacent to exactly :math:`4`
+    neighboring edges, hence the number of columns of :math:`A`: :math:`4*|E|`.
+    We write *the neighborhood* of edge :math:`e_i` as
+    :math:`\mathcal{N}(i) = (a(i), b(i), c(i), d(i))` where
+
+    1. :math:`a(i)` denotes the index of the *first* counter-clockwise
+    edge of the face *above* :math:`e_i`.
+
+    2. :math:`b(i)` denotes the index of the *second* counter-clockwise
+    edge of the face *above* :math:`e_i`.
+
+    3. :math:`c(i)` denotes the index of the *first* counter-clockwise edge
+    of the face *below* :math:`e_i`.
+
+    4. :math:`d(i)` denotes the index of the *second*
+    counter-clockwise edge of the face *below* :math:`e_i`.
+
+    .. figure:: ../_figures/meshcnn_edge_adjacency.svg
+        :align: center
+        :width: 80%
+
+        **Figure 1:** The neighbors of edge :math:`\mathbf{e_1}`
+        are :math:`\mathbf{e_2}, \mathbf{e_3}, \mathbf{e_4}` and
+        :math:`\mathbf{e_5}`, respectively.
+        We write this as
+        :math:`\mathcal{N}(1) = (a(1), b(1), c(1), d(1)) = (2, 3, 4, 5)`
+
+
+    Because of this ordering constrait, :obj:`MeshCNNConv` **requires
+    that the columns of** :math:`A`
+    **be ordered in the following way**:
+
+    .. math::
+        &A[:,0] = (0, \text{The index of the "a" edge for edge } 0) \\
+        &A[:,1] = (0, \text{The index of the "b" edge for edge } 0) \\
+        &A[:,2] = (0, \text{The index of the "c" edge for edge } 0) \\
+        &A[:,3] = (0, \text{The index of the "d" edge for edge } 0) \\
+        \vdots \\
+        &A[:,4*|E|-4] =
+            \bigl(|E|-1,
+                a\bigl(|E|-1\bigr)\bigr) \\
+        &A[:,4*|E|-3] =
+            \bigl(|E|-1,
+                b\bigl(|E|-1\bigr)\bigr) \\
+        &A[:,4*|E|-2] =
+            \bigl(|E|-1,
+                c\bigl(|E|-1\bigr)\bigr) \\
+        &A[:,4*|E|-1] =
+            \bigl(|E|-1,
+                d\bigl(|E|-1\bigr)\bigr)
+
+
+    Stated a bit more compactly, for every edge :math:`e_i` in the input mesh,
+    :math:`A`, should have the following entries
+
+    .. math::
+        A[:, 4*i] &= (i, a(i)) \\
+        A[:, 4*i + 1] &= (i, b(i)) \\
+        A[:, 4*i + 2] &= (i, c(i)) \\
+        A[:, 4*i + 3] &= (i, d(i))
+
+    To summarize so far, we have defined 3 things:
+
+    1. The activation of the prior (e.g. :math:`k` th) layer,
+    :math:`X^{(k)} \in \mathbb{R}^{|E| \times \text{Dim-Out}(k)}`
+
+    2. The edge adjacency matrix and the definition of edge adjacency.
+    :math:`A \in \{0,...,|E|-1\}^{2 \times 4*|E|}`
+
+    3. The ways the columns of :math:`A` must be ordered.
+
+
+
+    We are now finally able to define the :obj:`MeshCNNConv` class/layer.
+    In the following definition
+    we assume :obj:`MeshCNNConv` is at the :math:`k+1` th layer of our
+    neural network.
+
+    The :obj:`MeshCNNConv` layer is a function,
+
+    .. math::
+        \text{MeshCNNConv}^{(k+1)}(X^{(k)}, A) = X^{(k+1)},
+
+    that, given the prior layer's output
+    :math:`X^{(k)} \in \mathbb{R}^{|E| \times \text{Dim-Out}(k)}`
+    and the edge adjacency matrix :math:`A`
+    of the input mesh (graph) :math:`\mathcal{m}` ,
+    returns a new edge feature tensor
+    :math:`X^{(k+1)} \in \mathbb{R}^{|E| \times \text{Dim-Out}(k+1)}`,
+    where the :math:`i` th row of :math:`X^{(k+1)}`, denoted by
+    :math:`x^{(k+1)}_i`,
+    represents the :math:`\text{Dim-Out}(k+1)`-dimensional feature vector
+    of edge :math:`e_i`, **and is defined as follows**:
+
+    .. math::
+        x^{(k+1)}_i &= W^{(k+1)}_0 x^{(k)}_i \\
+        &+ W^{(k+1)}_1 \bigl| x^{(k)}_{a(i)} - x^{(k)}_{c(i)} \bigr| \\
+        &+ W^{(k+1)}_2 \bigl( x^{(k)}_{a(i)} + x^{(k)}_{c(i)} \bigr) \\
+        &+ W^{(k+1)}_3 \bigl| x^{(k)}_{b(i)} - x^{(k)}_{d(i)} \bigr| \\
+        &+ W^{(k+1)}_4 \bigl( x^{(k)}_{b(i)} + x^{(k)}_{d(i)} \bigr).
+
+    :math:`W_0^{(k+1)},W_1^{(k+1)},W_2^{(k+1)},W_3^{(k+1)}, W_4^{(k+1)}
+    \in \mathbb{R}^{\text{Dim-Out}(k+1) \times \text{Dim-Out}(k)}`
+    are trainable linear functions (i.e. "the weights" of this layer).
+    :math:`x_i` is the :math:`\text{Dim-Out}(k)`-dimensional feature of
+    edge :math:`e_i` vector computed by the prior (e.g. :math:`k`) th layer.
+    :math:`x^{(k)}_{a(i)}, x^{(k)}_{b(i)}, x^{(k)}_{c(i)}`, and
+    :math:`x^{(k)}_{d(i)}` are the :math:`\text{Dim-Out}(k)`-feature vectors,
+    computed in the :math:`k` th layer, that are associated with the :math:`4`
+    neighboring edges of :math:`e_i`.
+
+
+    Args:
+        in_channels (int): Corresonds to :math:`\text{Dim-Out}(k)`
+            in the above overview. This
+            represents the output dimension of the prior layer. For the given
+            input mesh :math:`\mathcal{m} = (V, F)`, the prior layer is
+            expected to output a
+            :math:`X \in \mathbb{R}^{|E| \times \textit{in_channels}}`
+            feature matrix.
+            Assuming the instance of this class
+            is situated at layer :math:`k+1`, we write that
+            :math:`X^{(k)} \in \mathbb{R}^{|E| \times \textit{in_channels}}`.
+        out_channels (int): Corresponds to :math:`\text{Dim-Out}(k+1)` in the
+            above overview. This represents the output dimension of this layer.
+            Assuming the instance of this class
+            is situated at layer :math:`k+1`, we write that
+            :math:`X^{(k+1)}
+            \in \mathbb{R}^{|E| \times \textit{out_channels}}`.
+        kernels (torch.nn.ModuleList, optional): A list of length of 5,
+            where each
+            element is a :class:`torch.nn.module` (i.e a neural network),
+            that each MUST take as input a vector
+            of dimension :`obj:in_channels` and return a vector of dimension
+            :obj:`out_channels`. In particular,
+            `obj:kernels[0]` is :math:`W^{(k+1)}_0` in the above overview
+            (see :obj:`MeshCNNConv`), `obj:kernels[1]` is :math:`W^{(k+1)}_1`,
+            `obj:kernels[2]` is :math:`W^{(k+1)}_2`,
+            `obj:kernels[3]` is :math:`W^{(k+1)}_3`
+            `obj:kernels[4]` is :math:`W^{(k+1)}_4`.
+            Note that this input is optional, in which case
+            each of the 5 elements in the kernels will be a linear
+            neural network :class:`torch.nn.modules.Linear`
+            correctly configured to take as input
+            :attr:`in_channels`-dimensional vectors and return
+            a vector of dimensions :attr:`out_channels`.
+
+    Discussion:
+        The key difference that seperates :obj:`MeshCNNConv` from a traditional
+        message passing graph neural network is that :obj:`MeshCNNConv`
+        requires the set of neighbors for a node
+        :math:`\mathcal{N}(u) = (v_1, v_2, ...)`
+        to *be an ordered set* (i.e. a tuple). In
+        fact, :obj:`MeshCNNConv` goes further, requiring
+        that :math:`\mathcal{N}(u)` always return a set of size :math:`4`.
+        This is different to most message passing graph neural networks,
+        which assume that :math:`\mathcal{N}(u) = \{v_1, v_2, ...\}` returns an
+        ordered set. This lends :obj:`MeshCNNConv` more expressive power,
+        at the cost of no longer being permutation invariant to
+        :math:`\mathbb{S}_4`. Put more plainly, in tradition message passing
+        GNNs, the network is *unable* to distinguish one neighboring node
+        from another.
+        In constrast, in :obj:`MeshCNNConv`, each of the 4 neighbors has a
+        "role", either the "a", "b", "c", or "d" neighbor. We encode this fact
+        by requiring that :math:`\mathcal{N}` return the 4-tuple,
+        where the first component is the "a" neighbor, and so on.
+
+        To summarize this comparison, it may re-define
+        :obj:`MeshCNNConv` in terms of :math:`\text{UPDATE}` and
+        :math:`\text{AGGREGATE}`
+        functions, which is a general way to define a traditional GNN layer.
+        If we let :math:`x_i^{(k+1)}`
+        denote the output of a GNN layer for node :math:`i` at
+        layer :math:`k+1`, and let
+        :math:`\mathcal{N}(i)` denote the set of nodes adjacent
+        to node :math:`i`,
+        then we can describe the :math:`k+1` th layer as traditional GNN
+        as
+
+        .. math::
+            x_i^{(k+1)} = \text{UPDATE}^{(k+1)}\bigl(x^{(k)}_i,
+            \text{AGGREGATE}^{(k+1)}\bigl(\mathcal{N}(i)\bigr)\bigr).
+
+        Here, :math:`\text{UPDATE}^{(k+1)}` is a function of :math:`2`
+        :math:`\text{Dim-Out}(k)`-dimensional vectors, and returns a
+        :math:`\text{Dim-Out}(k+1)`-dimensional vector.
+        :math:`\text{AGGREGATE}^{(k+1)}` function
+        is a function of a *unordered set*
+        of nodes that are neighbors of node :math:`i`, as defined by
+        :math:`\mathcal{N}(i)`. Usually the size of this set varies across
+        different nodes :math:`i`, and one of the most basic examples
+        of such a function is the "sum aggregation", defined as
+        :math:`\text{AGGREGATE}^{(k+1)}(\mathcal{N}(i)) =
+        \sum_{j \in \mathcal{N}(i)} x^{(k)}_j`.
+        See
+        :class:`SumAggregation <torch_geometric.nn.aggr.basic.SumAggregation>`
+        for more.
+
+        In contrast, while :obj:`MeshCNNConv` 's :math:`\text{UPDATE}`
+        function follows
+        a tradition GNN, its :math:`\text{AGGREGATE}` is a function of a tuple
+        (i.e. an ordered set) of neighbors
+        rather than a unordered set of neighbors.
+        In particular, while the :math:`\text{UPDATE}`
+        function of :obj:`MeshCNNConv` for :math:`e_i` is
+
+        .. math::
+            x_i^{(k+1)} = \text{UPDATE}^{(k+1)}(x_i^{(k)}, s_i^{(k+1)})
+            = W_0^{(k+1)}x_i^{(k)} + s_i^{(k+1)},
+
+        in contrast, :obj:`MeshCNNConv` 's :math:`\text{AGGREGATE}` function is
+
+        .. math::
+            s_i^{(k+1)} = \text{AGGREGATE}^{(k+1)}(A, B, C, D)
+            &= W_1^{(k+1)}\bigl|A - C \bigr| \\
+            &= W_2^{(k+1)}\bigl(A + C \bigr) \\
+            &= W_3^{(k+1)}\bigl|B - D \bigr| \\
+            &= W_4^{(k+1)}\bigl(B + D \bigr),
+
+        where :math:`A=x_{a(i)}^{(k)}, B=x_{b(i)}^{(k)}, C=x_{c(i)}^{(k)},`
+        and :math:`D=x_{d(i)}^{(k)}`.
+
+        ..
+
+            The :math:`i` th row of
+            :math:`V \in \mathbb{R}^{|V| \times 3}`
+            holds the cartesian :math:`xyz`
+            coordinates for node :math:`v_i` in the mesh, and the :math:`j` th
+            column in :math:`F \in \{1,...,|V|\}^{3 \times |V|}`
+            holds the :math:`3` indices
+            :math:`(k,l,m)` that correspond to the :math:`3` nodes
+            :math:`(v_k, v_l, v_m)` that construct face :math:`j` of the mesh.
+    """
+    def __init__(self, in_channels: int, out_channels: int,
+                 kernels: Optional[ModuleList] = None):
+        super().__init__(aggr='add')
+        self.in_channels = in_channels
+        self.out_channels = out_channels
+
+        if kernels is None:
+            self.kernels = ModuleList(
+                [Linear(in_channels, out_channels) for _ in range(5)])
+
+        else:
+            # ensures kernels is properly formed, otherwise throws
+            # the appropriate error.
+            self._assert_kernels(kernels)
+            self.kernels = kernels
+
+    def forward(self, x: Tensor, edge_index: Tensor):
+        r"""Forward pass.
+
+        Args:
+            x(torch.Tensor): :math:`X^{(k)} \in
+                \mathbb{R}^{|E| \times \textit{in_channels}}`.
+                The edge feature tensor returned by the prior layer
+                (e.g. :math:`k`). The tensor is of shape
+                :math:`|E| \times \text{Dim-Out}(k)`, or equivalently,
+                :obj:`(|E|, self.in_channels)`.
+
+            edge_index(torch.Tensor):
+                :math:`A \in \{0,...,|E|-1\}^{2 \times 4*|E|}`.
+                The edge adjacency tensor of the networks input mesh
+                :math:`\mathcal{m} = (V, F)`. The edge adjacency tensor
+                **MUST** have the following form:
+
+                .. math::
+                    &A[:,0] = (0,
+                        \text{The index of the "a" edge for edge } 0) \\
+                    &A[:,1] = (0,
+                        \text{The index of the "b" edge for edge } 0) \\
+                    &A[:,2] = (0,
+                        \text{The index of the "c" edge for edge } 0) \\
+                    &A[:,3] = (0,
+                        \text{The index of the "d" edge for edge } 0) \\
+                    \vdots \\
+                    &A[:,4*|E|-4] =
+                        \bigl(|E|-1,
+                            a\bigl(|E|-1\bigr)\bigr) \\
+                    &A[:,4*|E|-3] =
+                        \bigl(|E|-1,
+                            b\bigl(|E|-1\bigr)\bigr) \\
+                    &A[:,4*|E|-2] =
+                        \bigl(|E|-1,
+                            c\bigl(|E|-1\bigr)\bigr) \\
+                    &A[:,4*|E|-1] =
+                        \bigl(|E|-1,
+                            d\bigl(|E|-1\bigr)\bigr)
+
+                See :obj:`MeshCNNConv` for what
+                "index of the 'a'(b,c,d) edge for edge i" means, and also
+                for the general definition of edge adjacency in MeshCNN.
+                These definitions are also provided in the
+                `paper <https://arxiv.org/abs/1809.05910>`_ itself.
+
+        Returns:
+           torch.Tensor:
+           :math:`X^{(k+1)} \in \mathbb{R}^{|E| \times \textit{out_channels}}`.
+           The edge feature tensor for this (e.g. the :math:`k+1` th) layer.
+           The :math:`i` th row of :math:`X^{(k+1)}` is computed according
+           to the formula
+
+            .. math::
+                x^{(k+1)}_i &= W^{(k+1)}_0 x^{(k)}_i \\
+                &+ W^{(k+1)}_1 \bigl| x^{(k)}_{a(i)} - x^{(k)}_{c(i)} \bigr| \\
+                &+ W^{(k+1)}_2 \bigl( x^{(k)}_{a(i)} + x^{(k)}_{c(i)} \bigr) \\
+                &+ W^{(k+1)}_3 \bigl| x^{(k)}_{b(i)} - x^{(k)}_{d(i)} \bigr| \\
+                &+ W^{(k+1)}_4 \bigl( x^{(k)}_{b(i)} + x^{(k)}_{d(i)} \bigr),
+
+            where :math:`W_0^{(k+1)},W_1^{(k+1)},
+            W_2^{(k+1)},W_3^{(k+1)}, W_4^{(k+1)}
+            \in \mathbb{R}^{\text{Dim-Out}(k+1) \times \text{Dim-Out}(k)}`
+            are the trainable linear functions (i.e. the trainable
+            "weights") of this layer, and
+            :math:`x^{(k)}_{a(i)}, x^{(k)}_{b(i)}, x^{(k)}_{c(i)}`,
+            :math:`x^{(k)}_{d(i)}` are the
+            :math:`\text{Dim-Out}(k)`-dimensional edge feature vectors
+            computed by the prior (:math:`k` th) layer,
+            that are associated with the :math:`4`
+            neighboring edges of :math:`e_i`.
+
+        """
+        return self.propagate(edge_index, x=x)
+
+    def message(self, x_j: Tensor) -> Tensor:
+        r"""The messaging passing step of :obj:`MeshCNNConv`.
+
+
+        Args:
+          x_j: A :obj:`[4*|E|, num_node_features]` tensor.
+          Its ith row holds the value
+            stored by the source node in the previous layer of edge i.
+
+        Returns:
+            A :obj:`[|E|, num_node_features]` tensor,
+            whose ith row will be the value
+            that the target node of edge i will receive.
+        """
+        # The following variables names are taken from the paper
+        # MeshCNN computes the features associated with edge
+        # e by (|a - c|, a + c, |b - c|, b + c), where a, b, c, d are the
+        # neighboring edges of e, a being the 1 edge of the upper face,
+        # b being the second edge of the upper face, c being the first edge
+        # of the lower face,
+        # and d being the second edge of the lower face of the input Mesh
+
+        # TODO: It is unclear  if view is faster. If it is not,
+        # then we should prefer the strided method commented out below
+
+        E4, in_channels = x_j.size()  # E4 = 4|E|, i.e. num edges in line graph
+        # Option 1
+        n_a = x_j[0::4]  # shape: |E| x in_channels
+        n_b = x_j[1::4]  # shape: |E| x in_channels
+        n_c = x_j[2::4]  # shape: |E| x in_channels
+        n_d = x_j[3::4]  # shape: |E| x in_channels
+        m = torch.empty(E4, self.out_channels)
+        m[0::4] = self.kernels[1].forward(torch.abs(n_a - n_c))
+        m[1::4] = self.kernels[2].forward(n_a + n_c)
+        m[2::4] = self.kernels[3].forward(torch.abs(n_b - n_d))
+        m[3::4] = self.kernels[4].forward(n_b + n_d)
+        return m
+
+        # Option 2
+        # E4, in_channels = x_j.size()
+        # E = E4 // 4
+        # x_j = x_j.view(E, 4, in_channels)  # shape: (|E| x 4 x in_channels)
+        # n_a, n_b, n_c, n_d = x_j.unbind(
+        #     dim=1)  # shape: (4 x |E| x in_channels)
+        # m = torch.stack(
+        #     [
+        #         (n_a - n_c).abs(),  # shape: |E| x in_channels
+        #         n_a + n_c,
+        #         (n_b - n_d).abs(),
+        #         n_b + n_d,
+        #     ],
+        #     dim=1)  # shape: (|E| x 4 x in_channels)
+        # m.view(E4, in_channels)  # shape 4*|E| x in_channels
+        # return m
+
+    def update(self, inputs: Tensor, x: Tensor) -> Tensor:
+        r"""The UPDATE step, in reference to the UPDATE and AGGREGATE
+        formulation of message passing convolution.
+
+        Args:
+           inputs(torch.Tensor): The :attr:`in_channels`-dimensional vector
+            returned by aggregate.
+           x(torch.Tensor): :math:`X^{(k)}`. The original inputs to this layer.
+
+        Returns:
+            torch.Tensor: :math:`X^{(k+1)}`. The output of this layer, which
+            has shape :obj:`(|E|, out_channels)`.
+        """
+        return self.kernels[0].forward(x) + inputs
+
+    def _assert_kernels(self, kernels: ModuleList):
+        r"""Ensures that :obj:`kernels` is a list of 5 :obj:`torch.nn.Module`
+        modules (i.e. networks). In addition, it also ensures that each network
+        takes in input of dimension :attr:`in_channels`, and returns output
+        of dimension :attr:`out_channels`.
+        This method throws an error otherwise.
+
+        .. warn::
+            This method throws an error if :obj:`kernels` is
+            not valid. (Otherwise this method returns nothing)
+
+        """
+        assert isinstance(kernels, ModuleList), \
+            f"Parameter 'kernels' must be a \
+            torch.nn.module.ModuleList with 5 memebers, but we got \
+            {type(kernels)}."
+
+        assert len(kernels) == 5, "Parameter 'kernels' must be a \
+            torch.nn.module.ModuleList of with exactly 5 members"
+
+        for i, network in enumerate(kernels):
+            assert isinstance(network, Module), \
+                f"kernels[{i}] must be torch.nn.Module, got \
+                {type(network)}"
+            if not hasattr(network, "in_channels") and \
+                    not hasattr(network, "in_features"):
+                warn(f"kernel[{i}] does not have attribute \
+                            'in_channels' nor 'out_features'. The \
+                            network must take as input a \
+                            {self.in_channels}-dimensional tensor. \
+                            Still, assuming user configured \
+                            correctly. Continuing..")
+            else:
+                input_dimension = getattr(network, "in_channels",
+                                          network.in_features)
+                assert input_dimension == self.in_channels, f"The input \
+                dimension of the neural network in kernel[{i}] must \
+                be \
+                equal to 'in_channels', but input_dimension = \
+                {input_dimension}, and \
+                self.in_channels={self.in_channels}."
+
+            if not hasattr(network, "out_channels") and \
+                    not hasattr(network, "out_features"):
+                warn(f"kernel[{i}] does not have attribute \
+                                'in_channels' nor 'out_features'. The \
+                                network must take as input a \
+                                {self.in_channels}-dimensional tensor. \
+                                Still, assuming user configured \
+                                correctly. Continuing..")
+            else:
+                output_dimension = getattr(network, "out_channels",
+                                           network.out_features)
+                assert output_dimension == self.out_channels, f"The output \
+                    dimension of the neural network in kernel[{i}] must \
+                    be \
+                    equal to 'out_channels', but out_dimension = \
+                    {output_dimension}, and \
+                    self.out_channels={self.out_channels}."

torch_geometric/utils/__init__.py

@@ -57,6 +57,7 @@ from .embedding import get_embeddings, get_embeddings_hetero
 from ._trim_to_layer import trim_to_layer
 from .ppr import get_ppr
 from ._train_test_split_edges import train_test_split_edges
+from .influence import total_influence
 
 __all__ = [
     'scatter',
@@ -149,6 +150,7 @@ __all__ = [
     'trim_to_layer',
     'get_ppr',
     'train_test_split_edges',
+    'total_influence',
 ]
 
 # `structured_negative_sampling_feasible` is a long name and thus destroys the

torch_geometric/utils/influence.py

@@ -0,0 +1,271 @@
+from typing import List, Tuple, Union, cast
+
+import torch
+from torch import Tensor
+from torch.autograd.functional import jacobian
+from tqdm.auto import tqdm
+
+from torch_geometric.data import Data
+from torch_geometric.utils import k_hop_subgraph
+
+
+def k_hop_subsets_rough(
+    node_idx: int,
+    num_hops: int,
+    edge_index: Tensor,
+    num_nodes: int,
+) -> List[Tensor]:
+    r"""Return *rough* (possibly overlapping) *k*-hop node subsets.
+
+    This is a thin wrapper around
+    :pyfunc:`torch_geometric.utils.k_hop_subgraph` that *additionally* returns
+    **all** intermediate hop subsets rather than the full union only.
+
+    Parameters
+    ----------
+    node_idx: int
+        Index or indices of the central node(s).
+    num_hops: int
+        Number of hops *k*.
+    edge_index: Tensor
+        Edge index in COO format with shape :math:`[2, \text{num_edges}]`.
+    num_nodes: int
+        Total number of nodes in the graph. Required to allocate the masks.
+
+    Returns:
+    -------
+    List[Tensor]
+        A list ``[H₀, H₁, …, H_k]`` where ``H₀`` contains the seed node(s) and
+        ``H_i`` (for *i*>0) contains **all** nodes that are exactly *i* hops
+        away in the *expanded* neighbourhood (i.e. overlaps are *not*
+        removed).
+    """
+    col, row = edge_index
+
+    node_mask = row.new_empty(num_nodes, dtype=torch.bool)
+    edge_mask = row.new_empty(row.size(0), dtype=torch.bool)
+
+    node_idx_ = torch.tensor([node_idx], device=row.device)
+
+    subsets = [node_idx_]
+    for _ in range(num_hops):
+        node_mask.zero_()
+        node_mask[subsets[-1]] = True
+        torch.index_select(node_mask, 0, row, out=edge_mask)
+        subsets.append(col[edge_mask])
+
+    return subsets
+
+
+def k_hop_subsets_exact(
+    node_idx: int,
+    num_hops: int,
+    edge_index: Tensor,
+    num_nodes: int,
+    device: Union[torch.device, str],
+) -> List[Tensor]:
+    """Return **disjoint** *k*-hop subsets.
+
+    This function refines :pyfunc:`k_hop_subsets_rough` by removing nodes that
+    have already appeared in previous hops, ensuring that each subset contains
+    nodes *exactly* *i* hops away from the seed.
+    """
+    rough_subsets = k_hop_subsets_rough(node_idx, num_hops, edge_index,
+                                        num_nodes)
+
+    exact_subsets: List[List[int]] = [rough_subsets[0].tolist()]
+    visited: set[int] = set(exact_subsets[0])
+
+    for hop_subset in rough_subsets[1:]:
+        fresh = set(hop_subset.tolist()) - visited
+        visited |= fresh
+        exact_subsets.append(list(fresh))
+
+    return [
+        torch.tensor(s, device=device, dtype=edge_index.dtype)
+        for s in exact_subsets
+    ]
+
+
+def jacobian_l1(
+    model: torch.nn.Module,
+    data: Data,
+    max_hops: int,
+    node_idx: int,
+    device: Union[torch.device, str],
+    *,
+    vectorize: bool = True,
+) -> Tensor:
+    """Compute the **L1 norm** of the Jacobian for a given node.
+
+    The Jacobian is evaluated w.r.t. the node features of the *k*-hop induced
+    sub‑graph centred at ``node_idx``. The result is *folded back* onto the
+    **original** node index space so that the returned tensor has length
+    ``data.num_nodes``, where the influence score will be zero for nodes
+    outside the *k*-hop subgraph.
+
+    Notes:
+    -----
+    *   The function assumes that the model *and* ``data.x`` share the same
+        floating‑point precision (e.g. both ``float32`` or both ``float16``).
+
+    """
+    # Build the induced *k*-hop sub‑graph (with node re‑labelling).
+    edge_index = cast(Tensor, data.edge_index)
+    x = cast(Tensor, data.x)
+    k_hop_nodes, sub_edge_index, mapping, _ = k_hop_subgraph(
+        node_idx, max_hops, edge_index, relabel_nodes=True)
+    # get the location of the *center* node inside the sub‑graph
+    root_pos = cast(int, mapping[0])
+
+    # Move tensors & model to the correct device
+    device = torch.device(device)
+    sub_x = x[k_hop_nodes].to(device)
+    sub_edge_index = sub_edge_index.to(device)
+    model = model.to(device)
+
+    # Jacobian evaluation
+    def _forward(x: Tensor) -> Tensor:
+        return model(x, sub_edge_index)[root_pos]
+
+    jac = jacobian(_forward, sub_x, vectorize=vectorize)
+    influence_sub = jac.abs().sum(dim=(0, 2))  # Sum of L1 norm
+    num_nodes = cast(int, data.num_nodes)
+    # Scatter the influence scores back to the *global* node space
+    influence_full = torch.zeros(num_nodes, dtype=influence_sub.dtype,
+                                 device=device)
+    influence_full[k_hop_nodes] = influence_sub
+
+    return influence_full
+
+
+def jacobian_l1_agg_per_hop(
+    model: torch.nn.Module,
+    data: Data,
+    max_hops: int,
+    node_idx: int,
+    device: Union[torch.device, str],
+    vectorize: bool = True,
+) -> Tensor:
+    """Aggregate Jacobian L1 norms **per hop** for node_idx.
+
+    Returns a vector ``[I_0, I_1, …, I_k]`` where ``I_i`` is the *total*
+    influence exerted by nodes that are exactly *i* hops away from
+    ``node_idx``.
+    """
+    num_nodes = cast(int, data.num_nodes)
+    edge_index = cast(Tensor, data.edge_index)
+    influence = jacobian_l1(model, data, max_hops, node_idx, device,
+                            vectorize=vectorize)
+    hop_subsets = k_hop_subsets_exact(node_idx, max_hops, edge_index,
+                                      num_nodes, influence.device)
+    sigle_node_influence_per_hop = [influence[s].sum() for s in hop_subsets]
+    return torch.tensor(sigle_node_influence_per_hop, device=influence.device)
+
+
+def avg_total_influence(
+    influence_all_nodes: Tensor,
+    normalize: bool = True,
+) -> Tensor:
+    """Compute the *influence‑weighted receptive field* ``R``."""
+    avg_total_influences = torch.mean(influence_all_nodes, dim=0)
+    if normalize:  # nomalize by hop_0 (jacobian of the center node feature)
+        avg_total_influences = avg_total_influences / avg_total_influences[0]
+    return avg_total_influences
+
+
+def influence_weighted_receptive_field(T: Tensor) -> float:
+    """Compute the *influence‑weighted receptive field* ``R``.
+
+    Given an influence matrix ``T`` of shape ``[N, k+1]`` (i‑th row contains
+    the per‑hop influences of node *i*), the receptive field breadth *R* is
+    defined as the expected hop distance when weighting by influence.
+
+    A larger *R* indicates that, on average, influence comes from **farther**
+    hops.
+    """
+    normalised = T / torch.sum(T, dim=1, keepdim=True)
+    hops = torch.arange(T.shape[1]).float()  # 0 … k
+    breadth = normalised @ hops  # shape (N,)
+    return breadth.mean().item()
+
+
+def total_influence(
+    model: torch.nn.Module,
+    data: Data,
+    max_hops: int,
+    num_samples: Union[int, None] = None,
+    normalize: bool = True,
+    average: bool = True,
+    device: Union[torch.device, str] = "cpu",
+    vectorize: bool = True,
+) -> Tuple[Tensor, float]:
+    r"""Compute Jacobian‑based influence aggregates for *multiple* seed nodes.
+
+    For every sampled node :math:`v`, this method
+
+    1. evaluates the **L1‑norm** of the Jacobian of the model output at
+       :math:`v` w.r.t. the node features of its *k*-hop induced sub‑graph;
+    2. sums these scores **per hop** to obtain the influence vector
+       :math:`(I_{0}, I_{1}, \dots, I_{k})`;
+    3. optionally averages those vectors over all sampled nodes and
+       (optionally) normalises them by :math:`I_{0}`.
+
+    Args:
+        model (torch.nn.Module): A PyTorch Geometric‑compatible model with
+            forward signature ``model(x, edge_index) -> Tensor``.
+        data (torch_geometric.data.Data): Graph data object providing at least
+            :obj:`x` (node features) and :obj:`edge_index` (connectivity).
+        max_hops (int): Maximum hop distance :math:`k`.
+        num_samples (int, optional): Number of seed nodes to evaluate.
+            If :obj:`None`, all nodes are used. (default: :obj:`None`)
+        normalize (bool, optional): If :obj:`True`, divide each hop‑wise
+            average by the influence of hop 0. (default: :obj:`True`)
+        average (bool, optional): If :obj:`True`, return the hop‑wise **mean**
+            over all seed nodes (shape ``[k+1]``).
+            If :obj:`False`, return the full influence matrix of shape
+            ``[N, k+1]``. (default: :obj:`True`)
+        device (torch.device or str, optional): Device on which to perform the
+            computation. (default: :obj:`"cpu"`)
+        vectorize (bool, optional): Forwarded to
+            :func:`torch.autograd.functional.jacobian`.  Keeping this
+            :obj:`True` is often faster but increases memory usage.
+            (default: :obj:`True`)
+
+    Returns:
+        Tuple[Tensor, float]:
+            * **avg_influence** (*Tensor*):
+              • shape ``[k+1]`` if :obj:`average=True`;
+              • shape ``[N, k+1]`` otherwise.
+            * **R** (*float*): Influence‑weighted receptive‑field breadth
+              returned by :func:`influence_weighted_receptive_field`.
+
+    Example::
+        >>> avg_I, R = total_influence(model, data, max_hops=3,
+        ...                            num_samples=1000)
+        >>> avg_I
+        tensor([1.0000, 0.1273, 0.0142, 0.0019])
+        >>> R
+        0.216
+    """
+    num_samples = data.num_nodes if num_samples is None else num_samples
+    num_nodes = cast(int, data.num_nodes)
+    nodes = torch.randperm(num_nodes)[:num_samples].tolist()
+
+    influence_all_nodes: List[Tensor] = [
+        jacobian_l1_agg_per_hop(model, data, max_hops, n, device,
+                                vectorize=vectorize)
+        for n in tqdm(nodes, desc="Influence")
+    ]
+    allnodes = torch.vstack(influence_all_nodes).detach().cpu()
+
+    # Average total influence at each hop
+    if average:
+        avg_influence = avg_total_influence(allnodes, normalize=normalize)
+    else:
+        avg_influence = allnodes
+
+    # Influence‑weighted receptive field
+    R = influence_weighted_receptive_field(allnodes)
+
+    return avg_influence, R