GCNConv

class stgraph.nn.GCNConv(in_channels: int, out_channels: int, activation: Callable[..., torch.Tensor] | None = None, bias: bool = True)

Bases: Module

Graph Convolutional Network Layer.

Vertex-centric implementation for Graph Convolutional Network (GCN) layer as described in Semi-supervised Classification with Graph Convolutional Networks.

A multi-layer GCN model has the following layer-wise propagation rule

\[H^{(l+1)} = \sigma \left( \tilde{D}^{-1/2} \tilde{A} \tilde{D}^{-1/2} H^{(l)} W^{(l)} \right)\]

• \(H^{(l)}\): Matrix of activations in the \(l\)-th layer; \(H^{(0)} = X\) is the input feature matrix.

• \(\sigma\): Activation function (e.g., ReLU).

• \(\tilde{A} = A + I_N\): Adjacency matrix of the graph with added self-connections.

• \(I_N\): Identity matrix.

• \(\tilde{D}_{ii} = \sum_j \tilde{A}_{ij}\): Degree matrix of \(\tilde{A}\).

• \(W^{(l)}\): Trainable weight matrix for the \(l\)-th layer.

Vertex-Centric Formula

The vertex-centric implementation can be achieved by aggregating all the features of the neighbouring nodes of the central node

\[h^{(l+1)} = \left( \sum_{\text{nb} \in \text{innbs}(v)} \text{nb}_{h^{(l)}} \cdot \text{nb}_{\text{norm}} \cdot \text{weight}_{\text{nb,v}} \right) \cdot v_{\text{norm}}\]

• \(h^{(l)}\): Activations of central-node in the \(l\)-th layer.

• \(\text{innbs}(v)\): In-neighbours of central-node \(v\).

• \(\text{weight}_{\text{nb,v}}\): Weight of edge from \(nb\) to \(v\). In case no edge weights are present, it is set to 1

• \(norm\): Node wise normalization factor, \(v_{\text{norm}} = \text{in_degrees(v)}^{-0.5}\).

Node Data

The following node data needs to be set using StaticGraph.set_ndata before calling the forward() method.

Node Property	Description	Type
norm	Node-wise normalization factor	A PyTorch Tensor of shape (num_nodes, 1), where dim=1 contains the node-wise normalization factor

Parameters:

• in_channels (int) – Size of input sample passed into the layer

• out_channels (int) – Size of output sample outputted by the layer

• activation (optional) – Non-linear activation function provided by PyTorch

• bias (bool, optional) – If set to True, learnable bias parameters are added to the layer

forward(graph: StaticGraph, h: Tensor, edge_weight: Tensor | None = None) → Tensor

Execute a single forward pass for the GCN layer.

Runs a single forward pass using the vertex-centric implementation of the GCN layer.

Parameters:

• graph (StaticGraph) – A StaticGraph graph object

• h (Tensor) – Input for the GCN forward pass

• edge_weight (Tensor, optional) – Edge weights for each edge in the graph

Returns:

The output after executing the GCN forward pass

Return type:

Tensor

Raises:

• KeyError – If norm n_data is not present for the graph

• ValueError – If norm n_data passed is not of the shape (num_nodes, 1)

Example

Example usage:

# Defining a method to run forward pass with multiple GCN layers

def forward(input: Tensor, layers: List[GCNConv], graph: StaticGraph):
    h = input
    for layer in layers:
        h = layer.forward(graph, h)
    return h

reset_parameters() → None

Reset the learnable weight and bias parameters.

The weight parameter is initialized using a Xavier Uniform distribution. The bias parameter is initialized by setting all values to zero.