CCXN_Layer#

Implementation of a simplified, convolutional version of CCXN layer from Hajij et. al: Cell Complex Neural Networks.

class topomodelx.nn.cell.ccxn_layer.CCXNLayer(in_channels_0, in_channels_1, in_channels_2, att: bool = False, **kwargs)[source]#

Layer of a Convolutional Cell Complex Network (CCXN).

Implementation of a simplified version of the CCXN layer proposed in [1].

This layer is composed of two convolutional layers: 1. A convolutional layer sending messages from nodes to nodes. 2. A convolutional layer sending messages from edges to faces. Optionally, attention mechanisms can be used.

Parameters:

in_channels_0int: Dimension of input features on nodes (0-cells).
in_channels_1int: Dimension of input features on edges (1-cells).
in_channels_2int: Dimension of input features on faces (2-cells).
attbool, default=False: Whether to use attention.
**kwargsoptional: Additional arguments for the modules of the CCXN layer.

Methods

`add_module`(name, module)	Add a child module to the current module.
`apply`(fn)	Apply `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])	Return an iterator over module buffers.
`children`()	Return an iterator over immediate children modules.
`compile`(args, *kwargs)	Compile this Module's forward using `torch.compile()`.
`cpu`()	Move all model parameters and buffers to the CPU.
`cuda`([device])	Move all model parameters and buffers to the GPU.
`double`()	Casts all floating point parameters and buffers to `double` datatype.
`eval`()	Set the module in evaluation mode.
`extra_repr`()	Return the extra representation of the module.
`float`()	Casts all floating point parameters and buffers to `float` datatype.
`forward`(x_0, x_1, adjacency_0, incidence_2_t)	Forward pass.
`get_buffer`(target)	Return the buffer given by `target` if it exists, otherwise throw an error.
`get_extra_state`()	Return any extra state to include in the module's state_dict.
`get_parameter`(target)	Return the parameter given by `target` if it exists, otherwise throw an error.
`get_submodule`(target)	Return the submodule given by `target` if it exists, otherwise throw an error.
`half`()	Casts all floating point parameters and buffers to `half` datatype.
`ipu`([device])	Move all model parameters and buffers to the IPU.
`load_state_dict`(state_dict[, strict, assign])	Copy parameters and buffers from `state_dict` into this module and its descendants.
`modules`([remove_duplicate])	Return an iterator over all modules in the network.
`mtia`([device])	Move all model parameters and buffers to the MTIA.
`named_buffers`([prefix, recurse, ...])	Return an iterator over module buffers, yielding both the name of the buffer as well as the buffer itself.
`named_children`()	Return 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])	Return 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, ...])	Return an iterator over module parameters, yielding both the name of the parameter as well as the parameter itself.
`parameters`([recurse])	Return an iterator over module parameters.
`register_backward_hook`(hook)	Register a backward hook on the module.
`register_buffer`(name, tensor[, persistent])	Add a buffer to the module.
`register_forward_hook`(hook, *[, prepend, ...])	Register a forward hook on the module.
`register_forward_pre_hook`(hook, *[, ...])	Register a forward pre-hook on the module.
`register_full_backward_hook`(hook[, prepend])	Register a backward hook on the module.
`register_full_backward_pre_hook`(hook[, prepend])	Register a backward pre-hook on the module.
`register_load_state_dict_post_hook`(hook)	Register a post-hook to be run after module's `load_state_dict()` is called.
`register_load_state_dict_pre_hook`(hook)	Register a pre-hook to be run before module's `load_state_dict()` is called.
`register_module`(name, module)	Alias for `add_module()`.
`register_parameter`(name, param)	Add a parameter to the module.
`register_state_dict_post_hook`(hook)	Register a post-hook for the `state_dict()` method.
`register_state_dict_pre_hook`(hook)	Register a pre-hook for the `state_dict()` method.
`requires_grad_`([requires_grad])	Change if autograd should record operations on parameters in this module.
`set_extra_state`(state)	Set extra state contained in the loaded state_dict.
`set_submodule`(target, module[, strict])	Set the submodule given by `target` if it exists, otherwise throw an error.
`share_memory`()	See `torch.Tensor.share_memory_()`.
`state_dict`(*args[, destination, prefix, ...])	Return a dictionary containing references to the whole state of the module.
`to`(args, *kwargs)	Move and/or cast the parameters and buffers.
`to_empty`(*, device[, recurse])	Move the parameters and buffers to the specified device without copying storage.
`train`([mode])	Set the module in training mode.
`type`(dst_type)	Casts all parameters and buffers to `dst_type`.
`xpu`([device])	Move all model parameters and buffers to the XPU.
`zero_grad`([set_to_none])	Reset gradients of all model parameters.

__call__

References

[1]

Hajij, Istvan, Zamzmi. Cell complex neural networks. Topological data analysis and beyond workshop at NeurIPS 2020. https://arxiv.org/pdf/2010.00743.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.

forward(x_0, x_1, adjacency_0, incidence_2_t, x_2=None)[source]#

Forward pass.

The forward pass was initially proposed in [1]_. Its equations are given in [2]_ and graphically illustrated in [3]_.

The forward pass of this layer is composed of two steps.

The convolution from nodes to nodes is given by an adjacency message passing scheme (AMPS):

\[\begin{split}\begin{align*} &🟥 \quad m_{y \rightarrow \{z\} \rightarrow x}^{(0 \rightarrow 1 \rightarrow 0)} = M_{\mathcal{L}_\uparrow}(h_x^{(0)}, h_y^{(0)}, \Theta^{(y \rightarrow x)})\\ &🟧 \quad m_x^{(0 \rightarrow 1 \rightarrow 0)} = \text{AGG}_{y \in \mathcal{L}_\uparrow(x)}(m_{y \rightarrow \{z\} \rightarrow x}^{0 \rightarrow 1 \rightarrow 0})\\ &🟩 \quad m_x^{(0)} = m_x^{(0 \rightarrow 1 \rightarrow 0)}\\ &🟦 \quad h_x^{t+1,(0)} = U^{t}(h_x^{(0)}, m_x^{(0)}) \end{align*}\end{split}\]

The convolution from edges to faces is given by cohomology message passing scheme, using the coboundary neighborhood:

\[\begin{split}\begin{align*} &🟥 \quad m_{y \rightarrow x}^{(r' \rightarrow r)} = M^t_{\mathcal{C}}(h_{x}^{t,(r)}, h_y^{t,(r')}, x, y)\\ &🟧 \quad m_x^{(r' \rightarrow r)} = \text{AGG}_{y \in \mathcal{C}(x)} m_{y \rightarrow x}^{(r' \rightarrow r)}\\ &🟩 \quad m_x^{(r)} = m_x^{(r' \rightarrow r)}\\ &🟦 \quad h_{x}^{t+1,(r)} = U^{t,(r)}(h_{x}^{t,(r)}, m_{x}^{(r)}) \end{align*}\end{split}\]

Parameters:

x_0torch.Tensor, shape = (n_0_cells, channels): Input features on the nodes of the cell complex.
x_1torch.Tensor, shape = (n_1_cells, channels): Input features on the edges of the cell complex.
adjacency_0torch.sparse, shape = (n_0_cells, n_0_cells): Neighborhood matrix mapping nodes to nodes (A_0_up).
incidence_2_ttorch.sparse, shape = (n_2_cells, n_1_cells): Neighborhood matrix mapping edges to faces (B_2^T).
x_2torch.Tensor, shape = (n_2_cells, channels): Input features on the faces of the cell complex. Optional, only required if attention is used between edges and faces.

Returns:

torch.Tensor, shape = (1, num_classes): Output prediction on the entire cell complex.