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')

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.

Methods

add_module(name, module)	Adds a child module to the current module.
aggr_norm_func(conv_operator, x)	Perform aggregation normalization.
apply(fn)	Applies fn recursively to every submodule (as returned by .children()) as well as self.
bfloat16()	Casts all floating point parameters and buffers to bfloat16 datatype.
buffers([recurse])	Returns an iterator over module buffers.
chebyshev_conv(conv_operator, conv_order, x)	Perform Chebyshev convolution.
children()	Returns an iterator over immediate children modules.
cpu()	Moves all model parameters and buffers to the CPU.
cuda([device])	Moves all model parameters and buffers to the GPU.
double()	Casts all floating point parameters and buffers to double datatype.
eval()	Sets the module in evaluation mode.
extra_repr()	Set the extra representation of the module
float()	Casts all floating point parameters and buffers to float datatype.
forward(x, laplacian_down, laplacian_up)	Forward computation ([2]_ and [3]_).
get_buffer(target)	Returns the buffer given by target if it exists, otherwise throws an error.
get_extra_state()	Returns any extra state to include in the module's state_dict.
get_parameter(target)	Returns the parameter given by target if it exists, otherwise throws an error.
get_submodule(target)	Returns the submodule given by target if it exists, otherwise throws an error.
half()	Casts all floating point parameters and buffers to half datatype.
ipu([device])	Moves all model parameters and buffers to the IPU.
load_state_dict(state_dict[, strict])	Copies parameters and buffers from state_dict into this module and its descendants.
modules()	Returns an iterator over all modules in the network.
named_buffers([prefix, recurse, ...])	Returns an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
named_children()	Returns an iterator over immediate children modules, yielding both the name of the module as well as the module itself.
named_modules([memo, prefix, remove_duplicate])	Returns an iterator over all modules in the network, yielding both the name of the module as well as the module itself.
named_parameters([prefix, recurse, ...])	Returns an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
parameters([recurse])	Returns an iterator over module parameters.
register_backward_hook(hook)	Registers a backward hook on the module.
register_buffer(name, tensor[, persistent])	Adds a buffer to the module.
register_forward_hook(hook, *[, prepend, ...])	Registers a forward hook on the module.
register_forward_pre_hook(hook, *[, ...])	Registers a forward pre-hook on the module.
register_full_backward_hook(hook[, prepend])	Registers a backward hook on the module.
register_full_backward_pre_hook(hook[, prepend])	Registers a backward pre-hook on the module.
register_load_state_dict_post_hook(hook)	Registers a post hook to be run after module's load_state_dict is called.
register_module(name, module)	Alias for add_module().
register_parameter(name, param)	Adds a parameter to the module.
register_state_dict_pre_hook(hook)	These hooks will be called with arguments: self, prefix, and keep_vars before calling state_dict on self.
requires_grad_([requires_grad])	Change if autograd should record operations on parameters in this module.
reset_parameters([gain])	Reset learnable parameters.
set_extra_state(state)	This function is called from load_state_dict() to handle any extra state found within the state_dict.
share_memory()	See torch.Tensor.share_memory_()
state_dict(*args[, destination, prefix, ...])	Returns a dictionary containing references to the whole state of the module.
to(*args, **kwargs)	Moves and/or casts the parameters and buffers.
to_empty(*, device)	Moves the parameters and buffers to the specified device without copying storage.
train([mode])	Sets the module in training mode.
type(dst_type)	Casts all parameters and buffers to dst_type.
update(x)	Update embeddings on each cell (step 4).
xpu([device])	Moves all model parameters and buffers to the XPU.
zero_grad([set_to_none])	Sets gradients of all model parameters to zero.

__call__

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

aggr_norm_func(conv_operator, x)

Perform aggregation normalization.

chebyshev_conv(conv_operator, conv_order, x)

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)

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.

reset_parameters(gain: float = 1.414) → None

Reset learnable parameters.

Parameters:

gainfloat

Gain for the weight initialization.

Notes

This function will be called by subclasses of MessagePassing that have trainable weights.

update(x)

Update embeddings on each cell (step 4).

Parameters:

xtorch.Tensor, shape = (n_target_cells, out_channels)

Output features on target cells.

Returns:

torch.Tensor, shape = (n_target_cells, out_channels)

Updated output features on target cells.