Simplicial 2-complex convolutional neural network.

class topomodelx.nn.simplicial.scconv_layer.SCConvLayer(node_channels, edge_channels, face_channels)

Layer of a Simplicial 2-complex convolutional neural network (SCConv).

Implementation of the SCConv layer proposed in [1].

References

[1]

Bunch, You, Fung and Singh. Simplicial 2-complex convolutional neural nets. TDA and beyond, NeurIPS 2020 workshop. https://openreview.net/forum?id=TLbnsKrt6J-

[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.

forward(x_0, x_1, x_2, incidence_1, incidence_1_norm, incidence_2, incidence_2_norm, adjacency_up_0_norm, adjacency_up_1_norm, adjacency_down_1_norm, adjacency_down_2_norm)

Forward pass (see [2]_ and [3]_).

\[\begin{split}\begin{align*} &🟥 \quad m_{y\rightarrow x}^{(0\rightarrow 0)} = ({\tilde{A}_{\uparrow,0}})_{xy} \cdot h_y^{t,(0)} \cdot \Theta^{t,(0\rightarrow0)}\\ &🟥 \quad m^{(1\rightarrow0)}_{y\rightarrow x} = (B_1)_{xy} \cdot h_y^{t,(0)} \cdot \Theta^{t,(1\rightarrow 0)}\\ &🟥 \quad m^{(0 \rightarrow 1)}_{y \rightarrow x} = (\tilde B_1)_{xy} \cdot h_y^{t,(0)} \cdot \Theta^{t,(0 \rightarrow1)}\\ &🟥 \quad m^{(1\rightarrow1)}_{y\rightarrow x} = ({\tilde{A}_{\downarrow,1}} + {\tilde{A}_{\uparrow,1}})_{xy} \cdot h_y^{t,(1)} \cdot \Theta^{t,(1\rightarrow1)}\\ &🟥 \quad m^{(2\rightarrow1)}_{y \rightarrow x} = (B_2)_{xy} \cdot h_y^{t,(2)} \cdot \Theta^{t,(2 \rightarrow1)}\\ &🟥 \quad m^{(1 \rightarrow 2)}_{y \rightarrow x} = (\tilde B_2)_{xy} \cdot h_y^{t,(1)} \cdot \Theta^{t,(1 \rightarrow 2)}\\ &🟥 \quad m^{(2 \rightarrow 2)}_{y \rightarrow x} = ({\tilde{A}_{\downarrow,2}})\_{xy} \cdot h_y^{t,(2)} \cdot \Theta^{t,(2 \rightarrow 2)}\\ &🟧 \quad m_x^{(0 \rightarrow 0)} = \sum_{y \in \mathcal{L}_\uparrow(x)} m_{y \rightarrow x}^{(0 \rightarrow 0)}\\ &🟧 \quad m_x^{(1 \rightarrow 0)} = \sum_{y \in \mathcal{C}(x)} m_{y \rightarrow x}^{(1 \rightarrow 0)}\\ &🟧 \quad m_x^{(0 \rightarrow 1)} = \sum_{y \in \mathcal{B}(x)} m_{y \rightarrow x}^{(0 \rightarrow 1)}\\ &🟧 \quad m_x^{(1 \rightarrow 1)} = \sum_{y \in (\mathcal{L}_\uparrow(x) + \mathcal{L}_\downarrow(x))} m_{y \rightarrow x}^{(1 \rightarrow 1)}\\ &🟧 \quad m_x^{(2 \rightarrow 1)} = \sum_{y \in \mathcal{C}(x)} m_{y \rightarrow x}^{(2 \rightarrow 1)}\\ &🟧 \quad m_x^{(1 \rightarrow 2)} = \sum_{y \in \mathcal{B}(x)} m_{y \rightarrow x}^{(1 \rightarrow 2)}\\ &🟧 \quad m_x^{(2 \rightarrow 2)} = \sum_{y \in \mathcal{L}_\downarrow(x)} m_{y \rightarrow x}^{(2 \rightarrow 2)}\\ &🟩 \quad m_x^{(0)} = m_x^{(1\rightarrow0)}+ m_x^{(0\rightarrow0)}\\ &🟩 \quad m_x^{(1)} = m_x^{(2\rightarrow1)}+ m_x^{(1\rightarrow1)}\\ &🟦 \quad h^{t+1, (0)}_x = \sigma(m_x^{(0)})\\ &🟦 \quad h^{t+1, (1)}_x = \sigma(m_x^{(1)})\\ &🟦 \quad h^{t+1, (2)}_x = \sigma(m_x^{(2)}) \end{align*}\end{split}\]

Parameters:

x_0: torch.Tensor, shape = (n_nodes, node_channels)

Input features on the nodes of the simplicial complex.

x_1: torch.Tensor, shape = (n_edges, edge_channels)

Input features on the edges of the simplicial complex.

x_2: torch.Tensor, shape = (n_faces, face_channels)

Input features on the faces of the simplicial complex.

incidence_1: torch.Tensor, shape = (n_faces, channels)

Incidence matrix of rank 1 \(B_1\).

incidence_1_norm: torch.Tensor

Normalized incidence matrix of rank 1 \(B^{~}_1\).

incidence_2: torch.Tensor

Incidence matrix of rank 2 \(B_2\).

incidence_2_norm: torch.Tensor

Normalized incidence matrix of rank 2 \(B^{~}_2\).

adjacency_up_0_norm: torch.Tensor

Normalized upper adjacency matrix of rank 0.

adjacency_up_1_norm: torch.Tensor

Normalized upper adjacency matrix of rank 1.

adjacency_down_1_norm: torch.Tensor

Normalized down adjacency matrix of rank 1.

adjacency_down_2_norm: torch.Tensor

Normalized down adjacency matrix of rank 2.

Returns:

tuple of tensors, shape = (x0_out, x1_out, x2_out)

Output features on the nodes of the simplicial complex.

Notes

For normalization of incidence matrices you may use the helper functions here: pyt-team/TopoModelX

reset_parameters() → None

Reset parameters.