Simplicial Convolutional Neural Network Layer.
- class topomodelx.nn.simplicial.scnn_layer.SCNNLayer(in_channels, out_channels, conv_order_down, conv_order_up, aggr_norm: bool = False, update_func=None, initialization: str = 'xavier_uniform')[source]#
Layer of a Simplicial Convolutional Neural Network (SCNN) [1].
- Parameters:
- in_channelsint
Dimension of input features.
- out_channelsint
Dimension of output features.
- conv_orderint
The order of the convolutions. if conv_order == 0:
the corresponding convolution is not performed.
down: for the lower convolutions.
up: for the upper convolutions.
Notes
This is Implementation of the SCNN layer.
References
[1]Yang, Isufi and Leus. Simplicial Convolutional Neural Networks (2021). https://arxiv.org/pdf/2110.02585.pdf
[2]Papillon, Sanborn, Hajij, Miolane. Equations of topological neural networks (2023). awesome-tnns/awesome-tnns
[3]Papillon, Sanborn, Hajij, Miolane. Architectures of topological deep learning: a survey on topological neural networks (2023). https://arxiv.org/abs/2304.10031.
Examples
Here we provide an example of pseudocode for SCNN layer input X: [n_simplices, in_channels] Lap_down, Lap_up: [n_simplices, n_simplices] conv_order_down: int, e.g., 2 conv_order_up: int, e.g., 2 output Y: [n_simplices, out_channels]
SCNN layer looks like:
- Y = torch.einsum(concat(X, Lap_down@X, Lap_down@Lap_down@X, Lap_up@X,
Lap_up@Lap_up@X), weight)
- where
- weight is the trainable parameters of dimension
[out_channels,in_channels, total_order]
total_order = 1 + conv_order_down + conv_order_up
to implement Lap_down@Lap_down@X, we consider chebyshev method to avoid matrix@matrix computation
- chebyshev_conv(conv_operator, conv_order, x)[source]#
Perform Chebyshev convolution.
- Parameters:
- conv_operatortorch.sparse, shape = (n_simplices,n_simplices)
Convolution operator e.g. adjacency matrix or the Hodge Laplacians.
- conv_orderint
The order of the convolution
- xtorch.Tensor, shape = (n_simplices,num_channels)
Input feature tensor.
- forward(x, laplacian_down, laplacian_up)[source]#
Forward computation ([2]_ and [3]_).
\[\begin{split}\begin{align*} &🟥 \quad m_{y \rightarrow \{z\} \rightarrow x}^{p,u,(1 \rightarrow 2 \rightarrow 1)} = ((L_{\uparrow,1})^u)\_{xy} \cdot h_y^{t,(1)} \cdot (\alpha^{t, p, u} \cdot I)\\ &🟥 \quad m_{y \rightarrow \{z\} \rightarrow x}^{p,d,(1 \rightarrow 0 \rightarrow 1)} = ((L_{\downarrow,1})^d)\_{xy} \cdot h_y^{t,(1)} \cdot (\alpha^{t, p, d} \cdot I)\\ &🟥 \quad m^{(1 \rightarrow 1)}\_{x \rightarrow x} = \alpha \cdot h_x^{t, (1)}\\ &🟧 \quad m_{x}^{p,u,(1 \rightarrow 2 \rightarrow 1)} = \sum_{y \in \mathcal{L}\_\uparrow(X)}m_{y \rightarrow \{z\} \rightarrow x}^{p,u,(1 \rightarrow 2 \rightarrow 1)}\\ &🟧 \quad m_{x}^{p,d,(1 \rightarrow 0 \rightarrow 1)} = \sum_{y \in \mathcal{L}\_\downarrow(X)}m_{y \rightarrow \{z\} \rightarrow x}^{p,d,(1 \rightarrow 0 \rightarrow 1)}\\ &🟧 \quad m^{(1 \rightarrow 1)}\_{x} = m^{(1 \rightarrow 1)}\_{x \rightarrow x}\\ &🟩 \quad m_x^{(1)} = m_x^{(1 \rightarrow 1)} + \sum_{p=1}^P( \sum_{u=1}^{U} m_{x}^{p,u,(1 \rightarrow 2 \rightarrow 1)} + \sum_{d=1}^{D} m_{x}^{p,d,(1 \rightarrow 0 \rightarrow 1)})\\ &🟦 \quad h_x^{t+1, (1)} = \sigma(m_x^{(1)}) \end{align*}\end{split}\]- Parameters:
- x: torch.Tensor, shape = (n_simplex,in_channels)
Input features on the simplices, e.g., nodes, edges, triangles, etc.
- laplacian: torch.sparse, shape = (n_simplices,n_simplices)
The Hodge Laplacian matrix. Can also be adjacency matrix, lower part, or upper part.
- Returns:
- torch.Tensor, shape = (n_edges, channels)
Output features on the edges of the simplical complex.