Simplicial: Add equations in docstrings of forward methods

[ninamiolane]

What?

We consider the layers implemented for the simplicial complex domain, i.e. the ones in nn/simplicial/*_layer.py.

Each Layer is a Python class that has a forward() method. The docstring of this forward method should give the message passing equation of the Layer that is being implemented.

For example, see how the docstring of the forward method of the HSNLayer here: https://github.com/pyt-team/TopoModelX/blob/712fe4d1711378d8666237627e20827393de7146/topomodelx/nn/simplicial/hsn_layer.py#L70

properly gives the equations:

        r"""Forward pass.

        The forward pass was initially proposed in [HRGZ22]_.
        Its equations are given in [TNN23]_ and graphically illustrated in [PSHM23]_.

        .. math::
            \begin{align*}
            &🟥 \quad m_{{y \rightarrow z}}^{(0 \rightarrow 0)} = \sigma ((A_{\uparrow,0})_{xy} \cdot h^{t,(0)}_y \cdot \Theta^{t,(0)1})\\
            &🟥 \quad m_{z \rightarrow x}^{(0 \rightarrow 0)}  = (A_{\uparrow,0})_{xy} \cdot m_{y \rightarrow z}^{(0 \rightarrow 0)} \cdot \Theta^{t,(0)2}\\
            &🟥 \quad m_{{y \rightarrow z}}^{(0 \rightarrow 1)}  = \sigma((B_1^T)_{zy} \cdot h_y^{t,(0)} \cdot \Theta^{t,(0 \rightarrow 1)})\\
            &🟥 \quad m_{z \rightarrow x)}^{(1 \rightarrow 0)}  = (B_1)_{xz} \cdot m_{z \rightarrow x}^{(0 \rightarrow 1)} \cdot \Theta^{t, (1 \rightarrow 0)}\\
            &🟧 \quad m_{x}^{(0 \rightarrow 0)}  = \sum_{z \in \mathcal{L}_\uparrow(x)} m_{z \rightarrow x}^{(0 \rightarrow 0)}\\
            &🟧 \quad m_{x}^{(1 \rightarrow 0)}  = \sum_{z \in \mathcal{C}(x)} m_{z \rightarrow x}^{(1 \rightarrow 0)}\\
            &🟩 \quad m_x^{(0)}  = m_x^{(0 \rightarrow 0)} + m_x^{(1 \rightarrow 0)}\\
            &🟦 \quad h_x^{t+1,(0)}  = I(m_x^{(0)})
            \end{align*}

However, some forward functions of the layers on the simplicial domain do not provide the mathematical equations associated with this message passing. We should add them.

Why?

The code is easier to read and understand if one can refer to the mathematical equation directly.

While the equation does not render very well in the docstring, it will render on the documentation website which will help the users.

Where?

The files to modify are:

• topomodelx/nn/simplicial/*_layer.py

NOTE: This issue only focus on layers within the simplicial domain. There will be other issues to add equations in docstrings for other topological domains.

How?

Go to the repository: https://github.com/awesome-tnns/awesome-tnns Go to the file: Simplicial_Complexes.md

For each layer file simplicial/*_layer.py, for each forward() method in that file:

• Find the equation corresponding to the forward you are looking at in Simplicial_Complexes.md.
• Copy that equation into the correct format into the docstring of the forward() method.
• ! Verify that the code in the forward() method indeed corresponds to the equation. If not, raise an issue.
• When merging your PR, verify that the documentation website has rendered the equation correctly.

Note: this last step might need to wait on the issue #165