### Model Instantiation and Optimizer Setup

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/hsn_train.ipynb

Example code demonstrating how to instantiate the Network model and set up an Adam optimizer for training.

```APIDOC
## Model Instantiation and Optimizer Setup

### Description
Example code demonstrating how to instantiate the Network model and set up an Adam optimizer for training.

### Method
N/A (Code Example)

### Endpoint
N/A (Code Example)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Model Initialization and Training Setup

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/allset_train.ipynb

This section covers the initialization of the `Network` model with specified hyperparameters and the setup of the optimizer and loss function for training.

```APIDOC
## Model Initialization and Training Setup

### Description
Initializes the `Network` model using hyperparameters derived from the data (e.g., `x_0s.shape[1]` for `in_channels`, `torch.unique(y).shape[0]` for `out_channels`). It also sets up the `Adam` optimizer and the `CrossEntropyLoss` function for training the model.

### Method
N/A (Script Execution)

### Endpoint
N/A (Local Script)

### Parameters
#### Model Hyperparameters
- **`in_channels`** (int) - Dimension of input features, derived from `x_0s.shape[1]`.
- **`hidden_channels`** (int) - Dimension of hidden features (e.g., 128).
- **`n_layers`** (int) - Number of layers in the base model (e.g., 1).
- **`mlp_num_layers`** (int) - Number of layers in the MLP (e.g., 1).
- **`out_channels`** (int) - Dimension of output features, derived from the number of unique classes in `y`.
- **`task_level`** (str) - Level of the task ('graph' or 'node'), determined by `out_channels`.

#### Training Setup
- **`opt`** (torch.optim.Adam) - Adam optimizer configured with model parameters and a learning rate of 0.01.
- **`loss_fn`** (torch.nn.CrossEntropyLoss) - Cross-entropy loss function for classification tasks.

### Request Example
N/A

### Response
#### Success Response (Output)
- **`model`**: An instance of the `Network` class, moved to the specified `device`.
- **`opt`**: An initialized Adam optimizer.
- **`loss_fn`**: An initialized CrossEntropyLoss function.

#### Response Example
```python
# Base model hyperparameters
in_channels = x_0s.shape[1]
hidden_channels = 128
n_layers = 1
mlp_num_layers = 1

# Readout hyperparameters
out_channels = torch.unique(y).shape[0]
task_level = "graph" if out_channels == 1 else "node"


model = Network(
    in_channels=in_channels,
    hidden_channels=hidden_channels,
    out_channels=out_channels,
    n_layers=n_layers,
    mlp_num_layers=mlp_num_layers,
    task_level=task_level,
).to(device)

# Optimizer and loss
opt = torch.optim.Adam(model.parameters(), lr=0.01)

# Categorial cross-entropy loss
loss_fn = torch.nn.CrossEntropyLoss()
```
```

--------------------------------

### Import Libraries and Setup

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/hypergat_train.ipynb

Imports necessary libraries including numpy, toponetx, torch, and scikit-learn. It also sets up the device for computation (GPU if available, otherwise CPU).

```python
import numpy as np
import toponetx as tnx
import torch
from sklearn.model_selection import train_test_split

from topomodelx.nn.hypergraph.hypergat import HyperGAT
from topomodelx.utils.sparse import from_sparse
```

```python
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(device)
```

--------------------------------

### Install TopoModelX

Source: https://github.com/pyt-team/topomodelx/blob/main/README.md

Commands to install the TopoModelX library using pip. It also includes instructions for installing PyTorch and related libraries (torch-scatter, torch-sparse, torch-cluster) with CUDA support if needed.

```bash
pip install topomodelx
```

```bash
pip install torch==2.0.1 --extra-index-url https://download.pytorch.org/whl/${CUDA}
pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.0.1+${CUDA}.html
pip install torch-cluster -f https://data.pyg.org/whl/torch-2.0.0+${CUDA}.html
```

--------------------------------

### Import Libraries and Setup

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/san_train.ipynb

Imports necessary libraries like numpy, toponetx, and torch. It also sets up PyTorch to use CUDA if available, otherwise defaults to CPU.

```python
import numpy as np
import toponetx as tnx
import torch

from topomodelx.nn.simplicial.san import SAN
from topomodelx.utils.sparse import from_sparse

%load_ext autoreload
%autoreload 2
```

```python
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(device)
```

--------------------------------

### Clone and install TopoModelX

Source: https://github.com/pyt-team/topomodelx/blob/main/README.md

Commands to clone the repository from GitHub and install the package in editable mode for development.

```bash
git clone git@github.com:pyt-team/TopoModelX.git
cd TopoModelX
pip install -e '.[all]'
```

--------------------------------

### Install TopoModelX and PyTorch Dependencies

Source: https://context7.com/pyt-team/topomodelx/llms.txt

Commands to install the TopoModelX package and the required PyTorch environment with CUDA support.

```bash
pip install topomodelx
pip install torch==2.0.1 --extra-index-url https://download.pytorch.org/whl/${CUDA}
pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.0.1+${CUDA}.html
```

--------------------------------

### Run tests and configure hooks

Source: https://github.com/pyt-team/topomodelx/blob/main/README.md

Commands to execute the project test suite and install pre-commit git hooks to ensure code quality.

```bash
pytest
pre-commit install
```

--------------------------------

### Complete Training Example for Simplicial Graph Network (SAN)

Source: https://context7.com/pyt-team/topomodelx/llms.txt

A comprehensive example demonstrating the end-to-end training process for a Simplicial Attention Network (SAN) on the Karate Club dataset. It covers data loading, preprocessing, model definition, and the training loop, including loss calculation and optimization.

```python
import numpy as np
import torch
import torch.nn.functional as F
import toponetx as tnx
from topomodelx.nn.simplicial.san import SAN
from topomodelx.utils.sparse import from_sparse

# 1. Load and prepare data
dataset = tnx.datasets.karate_club(complex_type="simplicial")

laplacian_down = from_sparse(dataset.down_laplacian_matrix(rank=1))
laplacian_up = from_sparse(dataset.up_laplacian_matrix(rank=1))
incidence_0_1 = from_sparse(dataset.incidence_matrix(rank=1))

x_0 = torch.tensor(np.stack(list(dataset.get_simplex_attributes("node_feat").values())), dtype=torch.float)
x_1 = torch.tensor(np.stack(list(dataset.get_simplex_attributes("edge_feat").values())), dtype=torch.float)
x = x_1 + torch.sparse.mm(incidence_0_1.T, x_0)

# Binary labels for nodes
y = torch.tensor([1,1,1,1,1,1,1,1,1,0,1,1,1,1,0,0,1,1,0,1,0,1,0,0,0,0,0,0,0,0,0,0,0,0])
y_onehot = F.one_hot(y, num_classes=2).float()

# 2. Define model
class SimplicalClassifier(torch.nn.Module):
    def __init__(self, in_channels, hidden_channels, out_channels):
        super().__init__()
        self.san = SAN(in_channels, hidden_channels, n_layers=2)
        self.linear = torch.nn.Linear(hidden_channels, out_channels)

    def forward(self, x, laplacian_up, laplacian_down, incidence):
        x = self.san(x, laplacian_up, laplacian_down)
        x = torch.sparse.mm(incidence, x)  # Project edge features to nodes
        return self.linear(x)

model = SimplicalClassifier(x.shape[-1], 16, 2)
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)

# 3. Training loop
for epoch in range(100):
    model.train()
    optimizer.zero_grad()

    logits = model(x, laplacian_up, laplacian_down, incidence_0_1)
    loss = F.cross_entropy(logits, y)

    loss.backward()
    optimizer.step()

    if (epoch + 1) % 20 == 0:
        pred = logits.argmax(dim=1)
        acc = (pred == y).float().mean()
        print(f"Epoch {epoch+1}: Loss={loss.item():.4f}, Accuracy={acc.item():.4f}")
```

--------------------------------

### PyTorch Model Initialization and Hyperparameter Setup

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/hmpnn_train.ipynb

Initializes a PyTorch model by determining output channels and task level from input data. It then instantiates the Network with specified in_channels, hidden_channels, out_channels, n_layers, and task_level, moving the model to the appropriate device.

```python
out_channels = torch.unique(y).shape[0]
task_level = "graph" if out_channels == 1 else "node"


model = Network(
    in_channels=in_channels,
    hidden_channels=hidden_channels,
    out_channels=out_channels,
    n_layers=n_layers,
    task_level=task_level,
).to(device)
```

--------------------------------

### Initialize Model, Loss, and Optimizer in PyTorch

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/cell/can_train.ipynb

Initializes the neural network model, defines the cross-entropy loss function, and sets up the Adam optimizer for training. This is a common setup for classification tasks.

```python
crit = torch.nn.CrossEntropyLoss()
opt = torch.optim.Adam(model.parameters(), lr=0.001)
model
```

--------------------------------

### Optimizer, Loss Function, and Data Masks Setup

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/hmpnn_train.ipynb

Configures the training process by setting up the Adam optimizer for the model's parameters, defining the CrossEntropyLoss function, and extracting training, validation, and testing masks from the dataset.

```python
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)
loss_fn = torch.nn.CrossEntropyLoss()


train_mask = dataset["train_mask"]
val_mask = dataset["val_mask"]
test_mask = dataset["test_mask"]
```

--------------------------------

### Configure Optimizer and Loss Function

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/hypergat_train.ipynb

Initializes the Adam optimizer and Mean Squared Error loss function for the neural network model. This setup is essential for gradient-based optimization.

```python
opt = torch.optim.Adam(model.parameters(), lr=0.01)
loss_fn = torch.nn.MSELoss()
```

--------------------------------

### Setup Device for PyTorch

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/cell/ccxn_train.ipynb

Determines if a CUDA-enabled GPU is available and sets the device accordingly. If a GPU is found, it will be used; otherwise, the computation will default to the CPU. This is crucial for optimizing performance in deep learning tasks.

```python
import torch

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(device)
```

--------------------------------

### Implement and Use HNHN for Hypergraph Node and Hyperedge Learning

Source: https://context7.com/pyt-team/topomodelx/llms.txt

Details the implementation of HNHN (Hypergraph Networks with Hyperedge Neurons) for simultaneous learning of node and hyperedge representations. The example shows model initialization with an incidence matrix and performing a forward pass to get outputs for both nodes and hyperedges.

```python
import torch
from topomodelx.nn.hypergraph.hnhn import HNHN

# Setup
n_nodes, n_edges = 150, 60
in_channels, hidden_channels = 24, 48

# Create incidence matrix
row = torch.randint(0, n_nodes, (400,))
col = torch.randint(0, n_edges, (400,))
incidence_1 = torch.sparse_coo_tensor(
    torch.stack([row, col]),
    torch.ones(400),
    (n_nodes, n_edges)
)

# Create HNHN model (requires incidence at init for weight computation)
model = HNHN(
    in_channels=in_channels,
    hidden_channels=hidden_channels,
    incidence_1=incidence_1,
    n_layers=2,
    layer_drop=0.2
)

# Node features
x_0 = torch.randn(n_nodes, in_channels)

# Forward pass
x_0_out, x_1_out = model(x_0, incidence_1)
print(f"Node output: {x_0_out.shape}")       # Node output: torch.Size([150, 48])
print(f"Hyperedge output: {x_1_out.shape}")  # Hyperedge output: torch.Size([60, 48])
```

--------------------------------

### Instantiate and Configure Network Model

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/cell/cwn_train.ipynb

Demonstrates how to extract input feature dimensions from data samples and instantiate the Network class. It also shows how to move the model to the appropriate compute device.

```python
in_channels_0 = x_0s[0].shape[-1]
in_channels_1 = x_1s[0].shape[-1]
in_channels_2 = x_2s[0].shape[-1]
model = Network(in_channels_0, in_channels_1, in_channels_2, hid_channels=16, num_classes=1, n_layers=2)
model = model.to(device)
```

--------------------------------

### Initialize Environment and Device

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/cell/can_train.ipynb

Sets up the necessary imports for TopoModelX and PyTorch, and automatically detects whether to use a GPU or CPU for computation.

```python
import numpy as np
import toponetx as tnx
import torch
from sklearn.model_selection import train_test_split
from torch_geometric.datasets import TUDataset
from torch_geometric.utils.convert import to_networkx
from topomodelx.nn.cell.can import CAN
from topomodelx.utils.sparse import from_sparse

torch.manual_seed(0)
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(device)
```

--------------------------------

### Initialize and Instantiate the Model

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/cell/ccxn_train.ipynb

Demonstrates how to calculate input channel dimensions from data and instantiate the custom Network class, moving it to the appropriate computation device.

```python
in_channels_0 = x_0s[0].shape[-1]
in_channels_1 = x_1s[0].shape[-1]
in_channels_2 = 5
num_classes = 2
model = Network(in_channels_0, in_channels_1, in_channels_2, num_classes, n_layers=2)
model = model.to(device)
```

--------------------------------

### Install PyTorch dependencies

Source: https://github.com/pyt-team/topomodelx/blob/main/README.md

Commands to install PyTorch and related geometric deep learning libraries (scatter, sparse, cluster) with specific CUDA support.

```bash
pip install torch==2.0.1 --extra-index-url https://download.pytorch.org/whl/${CUDA}
pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.0.1+${CUDA}.html
pip install torch-cluster -f https://data.pyg.org/whl/torch-2.0.0+${CUDA}.html
```

--------------------------------

### Python Fit-Predict Method Example

Source: https://github.com/pyt-team/topomodelx/blob/main/docs/contributing/index.rst

An example of a Python 'fit_predict' method docstring, adapted from Scikit-Learn. It demonstrates how to document parameters, return values, and the method's functionality, which is equivalent to calling fit() followed by predict().

```python
def fit_predict(self, X, y=None, sample_weight=None):
    """Compute cluster centers and predict cluster index for each sample.

    Convenience method; equivalent to calling fit(X) followed by predict(X).

    Parameters
    ----------
    X : {array-like, sparse_matrix} of shape = (..., n_features)
       New data to transform.
    y : Ignored
       Not used, present here for API consistency by convention.
    sample_weight : array-like, shape [...,], optional
       The weights for each observation in X. If None, all observations
       are assigned equal weight (default: None).

    Returns
    -------
    labels : array, shape = (...,)
       Index of the cluster each sample belongs to.
    """
    return self.fit(X, sample_weight=sample_weight).labels_
```

--------------------------------

### Initialize Model and Optimizer

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/sccnn_train.ipynb

Sets up the input features, laplacians, incidence matrices, and initializes the model and Adam optimizer for training.

```python
x_all = (x_0, x_1, x_2)
conv_order = 2
in_channels_all = (x_0.shape[-1], x_1.shape[-1], x_2.shape[-1])
intermediate_channels_all = (16, 16, 16)
num_layers = 2
out_channels = 2
laplacian_all = (laplacian_0, laplacian_down_1, laplacian_up_1, laplacian_down_2, laplacian_up_2)
incidence_all = (incidence_1, incidence_2)
model = Network(
    in_channels_all=in_channels_all,
    hidden_channels_all=intermediate_channels_all,
    out_channels=out_channels,
    conv_order=conv_order,
    max_rank=max_rank,
    update_func="sigmoid",
    n_layers=num_layers,
)
optimizer = torch.optim.Adam(model.parameters(), lr=0.1)
```

--------------------------------

### Set up development environment

Source: https://github.com/pyt-team/topomodelx/blob/main/README.md

Commands to create and activate a conda environment with the required Python version for TopoModelX development.

```bash
conda create -n tmx python=3.11.3
conda activate tmx
```

--------------------------------

### generate_trajectories

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/scone_train.ipynb

Generates trajectories on a simplicial complex by finding shortest paths between randomly selected start, middle, and end nodes.

```APIDOC
## generate_trajectories

### Description
Generates trajectories from nodes in the lower left corner to the upper right corner connected through a node in the middle.

### Method
```python
def generate_trajectories(
    sc: tnx.SimplicialComplex,
    coords: np.ndarray,
    n_max: int = 1000
) -> list[list[int]]:
    """
    Generate trajectories from nodes in the lower left corner to the upper right corner connected through a node in the middle.
    """
    # Get indices for start points in the lower left corner, mid points in the center region and end points in the upper right corner.
    N = len(sc)
    start_nodes = list(range(int(0.2 * N)))
    mid_nodes = list(range(int(0.4 * N), int(0.5 * N)))
    end_nodes = list(range(int(0.8 * N), N))
    all_triplets = list(product(start_nodes, mid_nodes, end_nodes))

    assert (
        len(all_triplets) >= n_max
    ), f"Only {len(all_triplets)} valid paths, but {n_max} requested. Try increasing the number of points in the simplicial complex."
    triplets = random.sample(all_triplets, n_max)

    # Compute pairwise distances and create a matrix representing the underlying graph.
    distance_matrix = distance.squareform(distance.pdist(coords))
    graph = sc.adjacency_matrix(0).toarray() * distance_matrix
    G = nx.from_numpy_array(graph)

    # Find shortest paths
    trajectories = []
    for s, m, e in triplets:
        path_1 = nx.shortest_path(G, s, m, weight="weight")
        path_2 = nx.shortest_path(G, m, e, weight="weight")
        trajectory = path_1[:-1] + path_2
        trajectories.append(trajectory)

    return trajectories
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Generate trajectories for training and evaluation
trajectories = generate_trajectories(sc, coords, 1200)
```

### Response
#### Success Response (200)
- **trajectories** (list[list[int]]) - A list of generated trajectories, where each trajectory is a list of node indices.
```

--------------------------------

### Initialize SCoNe Network Parameters

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/scone_train.ipynb

Sets up the initial hyperparameters and incidence matrices required for the SCoNe neural network architecture.

```python
in_channels = 1
hidden_channels = 16
out_channels = 1
n_layers = 6

incidence_1 = torch.Tensor(sc.incidence_matrix(1).toarray())
incidence_2 = torch.Tensor(sc.incidence_matrix(2).toarray())
adjacency = torch.Tensor(sc.adjacency_matrix(0).toarray())
```

--------------------------------

### Initialize Topomodelx Network and Hyperparameters

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/hnhn_train.ipynb

Sets up the hyperparameters for the neural network, including input/hidden/output channel dimensions, number of layers, and task level. It then instantiates the Network model and moves it to the specified device.

```python
# Base model hyperparameters
in_channels = x_0s.shape[1]
hidden_channels = 128
n_layers = 1
mlp_num_layers = 1

# Readout hyperparameters
out_channels = torch.unique(y).shape[0]
task_level = "graph" if out_channels == 1 else "node"


model = Network(
    in_channels=in_channels,
    hidden_channels=hidden_channels,
    out_channels=out_channels,
    n_layers=n_layers,
    incidence_1=incidence_1,
    task_level=task_level,
).to(device)
```

--------------------------------

### Unit Testing with Pytest

Source: https://github.com/pyt-team/topomodelx/blob/main/docs/contributing/index.rst

Example of a simple Python function and its corresponding test case using the assert statement, along with commands to execute tests.

```python
def add(x, y):
    return x + y

def test_capital_case():
    assert add(4, 5) == 9
```

```bash
pip install -e .[dev]
pytest test_add.py
pytest test/
```

--------------------------------

### Initialize Model and Training Components

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/unigcnii_train.ipynb

Sets up the model hyperparameters, optimizer, and loss functions required for training. It includes a helper function for calculating classification accuracy.

```python
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)
loss_fn = torch.nn.CrossEntropyLoss()

def acc_fn(y, y_hat):
    return (y == y_hat).float().mean()
```

--------------------------------

### Initialize Topomodelx Network and Hyperparameters

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/hypersage_train.ipynb

Sets up the hyperparameters for the Network model, including input/output dimensions, hidden layer size, and task level. It then instantiates the Network model and moves it to the specified device. Dependencies include PyTorch and the previously defined Network class.

```python
# Base model hyperparameters
in_channels = x_0s.shape[1]
hidden_channels = 128
n_layers = 1
mlp_num_layers = 1

# Readout hyperparameters
out_channels = torch.unique(y).shape[0]
task_level = "graph" if out_channels == 1 else "node"


model = Network(
    in_channels=in_channels,
    hidden_channels=hidden_channels,
    out_channels=out_channels,
    n_layers=n_layers,
    device=device,
    task_level=task_level,
).to(device)
```

--------------------------------

### Initialize Environment and Load Dataset

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/unisage_train.ipynb

Sets up the computational device and imports the Cora benchmark dataset using PyTorch Geometric. It extracts node features, labels, and connectivity masks.

```python
import numpy as np
import torch
import torch_geometric.datasets as geom_datasets
from torch_geometric.utils import to_undirected
from topomodelx.nn.hypergraph.unisage import UniSAGE

torch.manual_seed(0)
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

cora = geom_datasets.Planetoid(root="tmp/", name="cora")
data = cora.data
x_0s = data.x
y = data.y
edge_index = data.edge_index
train_mask = data.train_mask
val_mask = data.val_mask
test_mask = data.test_mask
```

--------------------------------

### Initialize Neural Network and Hyperparameters

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/unisage_train.ipynb

Sets up the hyperparameters for the neural network, including input, hidden, and output channel dimensions, and the task level (graph or node). It then instantiates the 'Network' class with these parameters and moves the model to the appropriate device (e.g., GPU).

```python
# Base model hyperparameters
in_channels = x_0s.shape[1]
hidden_channels = 128
n_layers = 1

# Readout hyperparameters
out_channels = torch.unique(y).shape[0]
task_level = "graph" if out_channels == 1 else "node"

model = Network(
    in_channels=in_channels,
    hidden_channels=hidden_channels,
    out_channels=out_channels,
    input_drop=0.2,
    layer_drop=0.2,
    n_layers=n_layers,
    task_level=task_level,
).to(device)
```

--------------------------------

### Initialize Device and Environment

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/sca_cmps_train.ipynb

Detects available hardware (GPU/CPU) and configures the execution environment for PyTorch operations.

```python
import torch
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(device)
```

--------------------------------

### Import Libraries for HMPNN Training

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/hmpnn_train.ipynb

Imports necessary libraries including PyTorch, PyTorch Geometric for datasets, scikit-learn for metrics, and the HMPNN model from topomodelx. This setup is crucial for building and training the neural network.

```python
import torch
import torch_geometric.datasets as geom_datasets
from sklearn.metrics import accuracy_score

from topomodelx.nn.hypergraph.hmpnn import HMPNN

torch.manual_seed(0)
```

--------------------------------

### Python Generic Docstring Template

Source: https://github.com/pyt-team/topomodelx/blob/main/docs/contributing/index.rst

A generic template for Python docstrings, illustrating the standard sections like summary, description, parameters, returns, notes, and examples. This structure helps in creating well-documented code.

```python
def my_method(self, my_param_1, my_param_2="vector"):
   r"""Write a one-line summary for the method.

   Write a description of the method, including "big O"
   (:math:`O\left(g\left(n\right)\right)`)
   complexities.

   Parameters
   ----------
   my_param_1 : array-like, shape = (..., dim)
      Write a short description of parameter my_param_1.
   my_param_2 : str, {"vector", "matrix"}
      Write a short description of parameter my_param_2.
      Optional, default: "vector".

   Returns
   -------
   my_result : array-like, shape = (..., dim, dim)
      Write a short description of the result returned by the method.

   Notes
   -----
   If relevant, provide equations with (:math:)
   describing computations performed in the method.

   Example
   -------
   Provide code snippets showing how the method is used.
   You can link to scripts of the examples/ directory.

   Reference
   ---------
   If relevant, provide a reference with associated pdf or
   wikipedia page.
   """
```

--------------------------------

### Initialize SCN2 Environment and Device

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/scn2_train.ipynb

Imports necessary libraries for simplicial neural networks and configures the computation device (CPU or GPU).

```python
import numpy as np
import toponetx as tnx
import torch
from sklearn.model_selection import train_test_split
from topomodelx.nn.simplicial.scn2 import SCN2
from topomodelx.utils.sparse import from_sparse

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(device)
```

--------------------------------

### Instantiate and Configure Neural Network Model (Python)

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/san_train.ipynb

This snippet shows the instantiation of the 'Network' model using the SAN architecture. It defines the number of layers and initializes the Adam optimizer with a learning rate of 0.1 for training the model.

```python
n_layers = 1
model = Network(
    in_channels=in_channels,
    hidden_channels=hidden_channels,
    out_channels=out_channels,
    n_layers=n_layers,
)
optimizer = torch.optim.Adam(model.parameters(), lr=0.1)
model
```

--------------------------------

### Get Simplicial Features in Python

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/sccnn_train.ipynb

This function retrieves features for nodes, edges, or faces based on the specified rank. It takes a dataset object and a rank (0 for nodes, 1 for edges, 2 for faces) as input and returns a PyTorch tensor of the features. Dependencies include torch and numpy.

```python
import torch
import numpy as np

"""A function to obtain features based on the input: rank
"""

def get_simplicial_features(dataset, rank):
    if rank == 0:
        which_feat = "node_feat"
    elif rank == 1:
        which_feat = "edge_feat"
    elif rank == 2:
        which_feat = "face_feat"
    else:
        raise ValueError(
            "input dimension must be 0, 1 or 2, because features are supported on nodes, edges and faces"
        )

    x = list(dataset.get_simplex_attributes(which_feat).values())
    return torch.tensor(np.stack(x))
```

```python
x_0 = get_simplicial_features(dataset, rank=0)
x_1 = get_simplicial_features(dataset, rank=1)
x_2 = get_simplicial_features(dataset, rank=2)
print(f"There are {x_0.shape[0]} nodes with features of dimension {x_0.shape[1]}.")
print(f"There are {x_1.shape[0]} edges with features of dimension {x_1.shape[1]}.")
print(f"There are {x_2.shape[0]} faces with features of dimension {x_2.shape[1]}.")
```

--------------------------------

### Initialize SCNN Environment and Dependencies

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/scnn_train.ipynb

Imports necessary libraries for simplicial complex manipulation and deep learning, including TopoNetX and PyTorch.

```python
import numpy as np
import toponetx as tnx
import torch
from sklearn.model_selection import train_test_split
from topomodelx.nn.simplicial.scnn import SCNN
from topomodelx.utils.sparse import from_sparse
```

--------------------------------

### Implement and Use CAN for Cell Complex Attention

Source: https://context7.com/pyt-team/topomodelx/llms.txt

Demonstrates the Cell Attention Network (CAN) for attention-based message passing on cell complexes. The example involves creating a cell complex, preparing neighborhood matrices and features, initializing the CAN model with attention lifting, and performing a forward pass to obtain edge outputs.

```python
import torch
import toponetx as tnx
from topomodelx.nn.cell.can import CAN
from topomodelx.utils.sparse import from_sparse

# Create cell complex from graph
G = tnx.datasets.karate_club()
cell_complex = tnx.CellComplex(G)

# Get neighborhood matrices
adjacency_0 = from_sparse(cell_complex.adjacency_matrix(rank=0))
down_laplacian_1 = from_sparse(cell_complex.down_laplacian_matrix(rank=1))
up_laplacian_1 = from_sparse(cell_complex.up_laplacian_matrix(rank=1))

# Prepare features
n_nodes = cell_complex.shape[0]
n_edges = cell_complex.shape[1]
in_channels_0, in_channels_1, out_channels = 8, 8, 16

x_0 = torch.randn(n_nodes, in_channels_0)
x_1 = torch.randn(n_edges, in_channels_1)

# Create CAN model
model = CAN(
    in_channels_0=in_channels_0,
    in_channels_1=in_channels_1,
    out_channels=out_channels,
    dropout=0.5,
    heads=2,
    concat=True,
    skip_connection=True,
    n_layers=2,
    att_lift=True,     # Lift node signals to edges
    pooling=False
)

# Forward pass
output = model(x_0, x_1, adjacency_0, down_laplacian_1, up_laplacian_1)
print(f"Edge output shape: {output.shape}")  # Edge output shape: torch.Size([78, 16])
```

--------------------------------

### Initialize and Configure Neural Network Model

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/dist2cycle_train.ipynb

Initializes an instance of the 'Network' class and sets up the Adam optimizer. This snippet demonstrates how to instantiate the model with specific channel counts, output channels, and number of layers, and then prepares it for training by defining an optimizer.

```python
out_channels = 2
n_layers = 1

model = Network(
    channels=channels_nodes,
    out_channels=out_channels,
    n_layers=3,
)
optimizer = torch.optim.Adam(model.parameters(), lr=0.1)
```

--------------------------------

### Generate Trajectories on Simplicial Complex (Python)

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/scone_train.ipynb

Generates trajectories on a simplicial complex by sampling triplets of nodes (start, middle, end) and computing shortest paths between them. It utilizes the underlying graph structure derived from the simplicial complex and node coordinates. The function returns a list of trajectories, where each trajectory is a list of node indices.

```python
import networkx as nx
import numpy as np
from scipy.spatial import distance
from itertools import product
import random
import toponetx as tnx

def generate_trajectories(
    sc: tnx.SimplicialComplex, coords: np.ndarray, n_max: int = 1000
) -> list[list[int]]:
    """
    Generate trajectories from nodes in the lower left corner to the upper right corner connected through a node in the middle.
    """
    # Get indices for start points in the lower left corner, mid points in the center region and end points in the upper right corner.
    N = len(sc)
    start_nodes = list(range(int(0.2 * N)))
    mid_nodes = list(range(int(0.4 * N), int(0.5 * N)))
    end_nodes = list(range(int(0.8 * N), N))
    all_triplets = list(product(start_nodes, mid_nodes, end_nodes))

    assert (
        len(all_triplets) >= n_max
    ), f"Only {len(all_triplets)} valid paths, but {n_max} requested. Try increasing the number of points in the simplicial complex."
    triplets = random.sample(all_triplets, n_max)

    # Compute pairwise distances and create a matrix representing the underlying graph.
    distance_matrix = distance.squareform(distance.pdist(coords))
    graph = sc.adjacency_matrix(0).toarray() * distance_matrix
    G = nx.from_numpy_array(graph)

    # Find shortest paths
    trajectories = []
    for s, m, e in triplets:
        path_1 = nx.shortest_path(G, s, m, weight="weight")
        path_2 = nx.shortest_path(G, m, e, weight="weight")
        trajectory = path_1[:-1] + path_2
        trajectories.append(trajectory)

    return trajectories
```

--------------------------------

### Initialize and Train Model

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/allset_train.ipynb

Configures model hyperparameters, instantiates the network, and sets up the Adam optimizer with CrossEntropyLoss for training.

```python
in_channels = x_0s.shape[1]
hidden_channels = 128
n_layers = 1
mlp_num_layers = 1
out_channels = torch.unique(y).shape[0]
task_level = "graph" if out_channels == 1 else "node"

model = Network(in_channels=in_channels, hidden_channels=hidden_channels, out_channels=out_channels, n_layers=n_layers, mlp_num_layers=mlp_num_layers, task_level=task_level).to(device)

opt = torch.optim.Adam(model.parameters(), lr=0.01)
loss_fn = torch.nn.CrossEntropyLoss()
```

--------------------------------

### Implement and Use CWN for Cell Complex Processing

Source: https://context7.com/pyt-team/topomodelx/llms.txt

Illustrates the CW Network (CWN) for processing cell complexes with features at multiple ranks (nodes, edges, faces). The example shows creating a cell complex, adding cells, obtaining relevant matrices, preparing features for different ranks, and initializing the CWN model.

```python
import torch
import toponetx as tnx
from topomodelx.nn.cell.cwn import CWN
from topomodelx.utils.sparse import from_sparse

# Create a cell complex
G = tnx.datasets.karate_club()
cell_complex = tnx.CellComplex(G)
# Add some 2-cells (faces)
cell_complex.add_cell([0, 1, 2], rank=2)
cell_complex.add_cell([1, 2, 3], rank=2)

# Get matrices
adjacency_0 = from_sparse(cell_complex.adjacency_matrix(rank=0))
incidence_2 = from_sparse(cell_complex.incidence_matrix(rank=2))
incidence_1_t = from_sparse(cell_complex.incidence_matrix(rank=1).T)

# Prepare features
n_nodes, n_edges, n_faces = cell_complex.shape[0], cell_complex.shape[1], cell_complex.shape[2]
in_channels_0, in_channels_1, in_channels_2 = 8, 8, 8
hid_channels = 32

x_0 = torch.randn(n_nodes, in_channels_0)
x_1 = torch.randn(n_edges, in_channels_1)
x_2 = torch.randn(n_faces, in_channels_2)

# Create CWN model
model = CWN(
    in_channels_0=in_channels_0,
    in_channels_1=in_channels_1,
    in_channels_2=in_channels_2,
    hid_channels=hid_channels,
    n_layers=2
)

# Note: The forward pass for CWN would typically involve passing x_0, x_1, x_2 and the relevant incidence/adjacency matrices.
```

--------------------------------

### Initialize Model, Optimizer, and Loss Function

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/scn2_train.ipynb

Initializes the 'Network' model, an Adam optimizer, and a Mean Squared Error (MSE) loss function. The model is moved to the specified device (e.g., GPU).

```python
n_layers = 2
model = Network(
    in_channels_0,
    in_channels_1,
    in_channels_2,
    out_channels,
    n_layers=n_layers,
)
model = model.to(device)
optimizer = torch.optim.Adam(model.parameters(), lr=0.1)
loss_fn = torch.nn.MSELoss()
```

--------------------------------

### Instantiate and Configure Neural Network (Python)

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/sccn_train.ipynb

Instantiates the 'Network' model with specified parameters (channels, output channels, max rank, layers, update function) and configures the Adam optimizer for training. This sets up the model for the node classification task.

```python
n_layers = 2
out_channels = 2

model = Network(
    channels=channels_nodes,
    out_channels=out_channels,
    max_rank=max_rank,
    n_layers=n_layers,
    update_func="sigmoid",
)
optimizer = torch.optim.Adam(model.parameters(), lr=0.1)
```

--------------------------------

### Initialize Training Environment and Trainer

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/combinatorial/hmc_train.ipynb

Detects available hardware (GPU or CPU) and initializes the Trainer object with the model, data loaders, and learning rate.

```python
import torch
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
trainer = Trainer(model, training_dataloader, testing_dataloader, 0.001, device)
```

--------------------------------

### Initialize SCCNN Environment

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/sccnn_train.ipynb

Imports necessary libraries and configures the environment for training a Simplicial Complex Convolutional Neural Network.

```python
import numpy as np
import toponetx as tnx
import torch
from sklearn.model_selection import train_test_split
from topomodelx.nn.simplicial.sccnn import SCCNN
from topomodelx.utils.sparse import from_sparse
%load_ext autoreload
%autoreload 2
```

--------------------------------

### Initialize HyperGAT Model

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/hypergat_train.ipynb

Sets hyperparameters for the HyperGAT model and the readout layer, then initializes the 'Network' model and moves it to the appropriate computation device (CPU or GPU).

```python
# Base model hyperparameters
in_channels = x_0s[0].shape[1]
hidden_channels = 32
out_dim = 1
n_layers = 3

# Readout hyperparameters
out_channels = 1
task_level = "graph"


model = Network(
    in_channels=in_channels,
    hidden_channels=hidden_channels,
    out_channels=out_channels,
    n_layers=n_layers,
    task_level=task_level,
).to(device)
```

--------------------------------

### Initialize Device and Load Cora Dataset

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/allset_transformer_train.ipynb

Detects the available compute device (GPU or CPU) and loads the Cora benchmark dataset using PyTorch Geometric.

```python
import torch
import torch_geometric.datasets as geom_datasets

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
cora = geom_datasets.Planetoid(root="tmp/", name="cora")
data = cora.data
x_0s = data.x
y = data.y
edge_index = data.edge_index
```

--------------------------------

### Initialize Network and Optimizer (PyTorch)

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/simplicial/scconv_train.ipynb

Initializes an instance of the 'Network' class with specified input and output channels, and number of layers. It also sets up the Adam optimizer to train the model's parameters with a learning rate of 0.1.

```python
n_layers = 1
model = Network(
    in_channels=in_channels,
    out_channels=out_channels,
    n_layers=n_layers,
)
optimizer = torch.optim.Adam(model.parameters(), lr=0.1)
```

--------------------------------

### Import Libraries and Set Device

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/unigcn_train.ipynb

Imports necessary libraries for Topomodelx, PyTorch, PyTorch Geometric, and scikit-learn. It also sets the computation device to GPU if available, otherwise defaults to CPU.

```python
import toponetx as tnx
import torch
from sklearn.model_selection import train_test_split
from torch_geometric.datasets import TUDataset
from torch_geometric.utils.convert import to_networkx

from topomodelx.nn.hypergraph.unigcn import UniGCN
from topomodelx.utils.sparse import from_sparse

torch.manual_seed(0)

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(device)
```

--------------------------------

### Initialize Topomodelx Imports

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/combinatorial/hmc_train.ipynb

Imports the essential modules for Topomodelx, including NumPy, TopoNetX, and PyTorch components required for combinatorial neural network operations.

```python
import numpy as np
import toponetx as tnx
import torch
from torch.utils.data import DataLoader, Dataset
from topomodelx.nn.combinatorial.hmc import HMC
```

--------------------------------

### Initialize HNHN Model and Device Configuration

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/hnhn_train.ipynb

This snippet initializes the HNHN model and sets up the computation device (GPU or CPU) based on availability. It imports necessary libraries for hypergraph neural networks and data manipulation.

```python
import numpy as np
import torch
import torch_geometric.datasets as geom_datasets
from torch_geometric.utils import to_undirected

from topomodelx.nn.hypergraph.hnhn import HNHN

torch.manual_seed(0)

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
print(device)
```

--------------------------------

### Initialize UniGIN Model

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/unigin_train.ipynb

Sets hyperparameters and instantiates the custom Network class for training.

```python
in_channels = x_1_list[0].shape[1]
hidden_channels = 32
n_layers = 3
mlp_num_layers = 1
input_drop = 0.2
layer_drop = 0.2
out_channels = 2
task_level = "graph"

model = Network(
    in_channels=in_channels,
    hidden_channels=hidden_channels,
    input_drop=input_drop,
    layer_drop=layer_drop,
    n_layers=n_layers,
    out_channels=out_channels,
    task_level=task_level,
).to(device)
```

--------------------------------

### Set up Loss Function and Optimizer

Source: https://github.com/pyt-team/topomodelx/blob/main/tutorials/hypergraph/dhgcn_train.ipynb

This code block configures the loss function and optimizer for the neural network training process. It specifies Mean Squared Error (MSE) as the loss function and Adam as the optimizer, with a learning rate of 0.1.

```python
loss_fn = torch.nn.MSELoss()
opt = torch.optim.Adam(model.parameters(), lr=0.1)
```