What?

We consider the layers implemented for the hypergraph domain, i.e. the ones in nn/hypergraph/*_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 UniGCNII here: https://github.com/pyt-team/TopoModelX/blob/main/topomodelx/nn/hypergraph/unigcnii_layer.py

properly gives the equations:

        The forward pass consists of:
        - two messages, and
        - a skip connection with a learned update function.

        1. Every hyper-edge sums up the features of its constituent edges:
        .. math::
            \begin{align*}
            & 🟥 \quad m_{y \rightarrow z}^{(0 \rightarrow 1)} = (B^T_1)\_{zy} \cdot h^{t,(0)}_y \\
            & 🟧 \quad m_z^{(0\rightarrow1)} = \sum_{y \in \mathcal{B}(z)} m_{y \rightarrow z}^{(0 \rightarrow 1)}
            \end{align*}

        2. The second message is normalized with the node and edge degrees:
        .. math::
            \begin{align*}
            & 🟥 \quad m_{z \rightarrow x}^{(1 \rightarrow 0)}  = B_1 \cdot m_z^{(0 \rightarrow 1)} \\
            & 🟧 \quad m_{x}^{(1\rightarrow0)}  = \frac{1}{\sqrt{d_x}}\sum_{z \in \mathcal{C}(x)} \frac{1}{\sqrt{d_z}}m_{z \rightarrow x}^{(1\rightarrow0)} \\
            \end{align*}

        3. The computed message is combined with skip connections and a linear transformation using hyperparameters alpha and beta:
        .. math::
            \begin{align*}
            & 🟩 \quad m_x^{(0)}  = m_x^{(1 \rightarrow 0)} \\
            & 🟦 \quad m_x^{(0)}  = ((1-\beta)I + \beta W)((1-\alpha)m_x^{(0)} + \alpha \cdot h_x^{t,(0)}) \\
            \end{align*}

However, some forward functions of the layers on the hypergraph 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/hypergraph/*_layer.py

NOTE: This issue only focus on layers within the hypergraph 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: Hypergraphs.md

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

Find the equation corresponding to the forward you are looking at in Hypergraphs.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.

pyt-team / TopoModelX

Hypergraph: Add equations in docstrings of forward methods #168

What?

Why?

Where?

How?