### Install TopoNetX from Source

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

Steps to clone the repository, update, and install in editable mode for development purposes.

```bash
git clone https://github.com/pyt-team/TopoNetX
cd TopoNetX
git pull
pip install -e '.[all]'
pre-commit install
```

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

### Installation

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

Instructions on how to install TopoNetX using pip and from source.

```APIDOC
## Installing TopoNetX

`TopoNetX` is available on PyPI and can be installed using `pip`:

```bash
pip install toponetx
```

## Install from source

To install the latest version from source, follow these steps:

1. Clone a copy of `TopoNetX` from source:

```bash
git clone https://github.com/pyt-team/TopoNetX
cd TopoNetX
```

2. If you have already cloned `TopoNetX` from source, update it:

```bash
git pull
```

3. Install `TopoNetX` in editable mode (requires `pip` ≥ 21.3 for [PEP 660](https://peps.python.org/pep-0610/) support):

```bash
pip install -e '.[all]'
```

4. Install pre-commit hooks:

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

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

### Install Development and Documentation Requirements

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

Pip commands to install the necessary packages for development testing and documentation building.

```bash
$ pip install -e .[dev]
$ pip install -e .[doc]
```

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

### Install TopoNetX via pip

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

Command to install the TopoNetX package from the Python Package Index (PyPI).

```bash
pip install toponetx
```

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

### Example 1: Creating a Simplicial Complex

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

Demonstrates how to create a SimplicialComplex, compute incidence matrices.

```APIDOC
## Example 1: creating a simplicial complex

```python
import toponetx as tnx

# Instantiate a SimplicialComplex object with a few simplices
sc = tnx.SimplicialComplex([[1, 2, 3], [2, 3, 4], [0, 1]])

# Compute the incidence matrix between 1-skeleton and 0-skeleton
B1 = sc.incidence_matrix(1)

# Compute the incidence matrix between 2-skeleton and 1-skeleton
B2 = sc.incidence_matrix(2)
```
```

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

### Example 3: Creating a Combinatorial Complex

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

Demonstrates how to create a CombinatorialComplex, add cells, and compute incidence matrices.

```APIDOC
## Example 3: creating a combinatorial complex

```python
import toponetx as tnx

# Instantiate a combinatorial complex object with a few cells
cc = tnx.CombinatorialComplex()

# Add some cells of different ranks after initialization
cc.add_cell([1, 2, 3], rank=2)
cc.add_cell([3, 4, 5], rank=2)
cc.add_cells_from([[2, 3, 4, 5], [3, 4, 5, 6, 7]], ranks=3)

# Compute the incidence matrix between cells of rank 0 and 2
B02 = cc.incidence_matrix(0, 2)

# Compute the incidence matrix between cells of rank 0 and 3
B03 = cc.incidence_matrix(0, 3)
```
```

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

### Example 2: Creating a Cell Complex

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

Demonstrates how to create a CellComplex, add edges, and compute Hodge Laplacian matrices.

```APIDOC
## Example 2: creating a cell complex

```python
import toponetx as tnx

# Instantiate a CellComplex object with a few cells
cx = tnx.CellComplex([[1, 2, 3, 4], [3, 4, 5, 6, 7, 8]], ranks=2)

# Add an edge (cell of rank 1) after initialization
cx.add_edge(0, 1)

# Compute the Hodge Laplacian matrix of dimension 1
L1 = cx.hodge_laplacian_matrix(1)

# Compute the Hodge Laplacian matrix of dimension 2
L2 = cx.hodge_laplacian_matrix(2)
```
```

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

### Scikit-Learn Style Method Implementation

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

A practical example of a method docstring following the Scikit-Learn style, detailing parameters and return values for a fit_predict method.

```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_
```

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

### Basic Test Function and Assertion

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

Example of a simple Python function and a test case using assert to verify its correctness.

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

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

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

### Scikit-Learn Fit Predict Example

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

An example of a filled-in docstring for the `fit_predict` method, following common conventions.

```APIDOC
## def fit_predict(self, X, y=None, sample_weight=None)

### Description
Compute cluster centers and predict cluster index for each sample.

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

### Parameters
#### Parameters
- **X** ({array-like, sparse_matrix} of shape=[..., n_features]) - Required - New data to transform.
- **y** (Ignored) - Optional - 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
#### Returns
- **labels** (array, shape=[...,]) - Index of the cluster each sample belongs to.
```

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

### Print NumPy Docstring Example

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

Python code to demonstrate how to access and print the docstring of a NumPy function.

```python
import numpy as np
print(np.mean.__doc__)
```

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

### Displaying Combinatorial Complex Image in TopoNetX

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/03_combinatorial_complexes.ipynb

This Python code snippet demonstrates how to display an image representing a combinatorial complex using the TopoNetX library and IPython.display. It requires the toponetx library to be installed.

```python
from IPython.display import Image

import toponetx as tnx

Image("ccc.png")
```

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

### Generic Python Docstring Template

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

A template demonstrating the structure of a Python docstring, including sections for parameters, return values, notes, and examples using reStructuredText.

```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.
    """
```

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

### Get Face Attributes from Simplicial Complex (Python)

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/01_simplicial_complexes.ipynb

Retrieves the values of a specified attribute for all faces in a simplicial complex. The `get_simplex_attributes` function returns a dictionary mapping faces to their attribute values. This data can then be processed, for example, into a NumPy array for further calculations.

```python
face_weights = ex2_sc.get_simplex_attributes("weight")
example2_face_values = np.array(list(face_weights.values()))

print(face_weights)
print(example2_face_values)
```

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

### Initialize TopoNetX Environment

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/01_simplicial_complexes.ipynb

Imports the necessary libraries, specifically numpy and toponetx, to begin working with topological structures.

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

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

### Initialize and Populate a Colored Hypergraph

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/04_colored_hypergraphs.ipynb

Demonstrates how to instantiate a ColoredHyperGraph object and add cells with specific ranks using the add_cell method. This allows for the construction of complex hypergraph structures where hyperedges are categorized by rank.

```python
import toponetx as tnx

example = tnx.ColoredHyperGraph()

example.add_cell([1, 2], rank=1)
print(example)

example.add_cell([1, 3], rank=1)
print(example)

example.add_cell([1, 2, 4, 3], rank=2)
print(example)

example.add_cell([2, 5], rank=1)
print(example)
```

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

### Create and Analyze a Simplicial Complex

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

Demonstrates initializing a SimplicialComplex and computing incidence matrices for different skeletons.

```python
import toponetx as tnx

# Instantiate a SimplicialComplex object with a few simplices
sc = tnx.SimplicialComplex([[1, 2, 3], [2, 3, 4], [0, 1]])

# Compute the incidence matrix between 1-skeleton and 0-skeleton
B1 = sc.incidence_matrix(1)

# Compute the incidence matrix between 2-skeleton and 1-skeleton
B2 = sc.incidence_matrix(2)
```

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

### Create and List Simplicial Complex with Faces

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/01_simplicial_complexes.ipynb

Shows how to instantiate a more complex structure by providing both edge and face sets, then listing the resulting simplices.

```python
edge_set = [[1, 2], [1, 3]]
face_set = [[2, 3, 4], [2, 4, 5]]
ex2_sc = tnx.SimplicialComplex(edge_set + face_set)
ex2_sc.simplices
```

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

### Creating and Populating Cell Complexes

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/02_cell_complexes.ipynb

Demonstrates how to initialize a CellComplex and add cells of different ranks using add_cell and add_cells_from methods.

```python
import toponetx as tnx

# Example 1: 1-dimensional complex
example_1 = tnx.CellComplex()
example_1.add_cell([1, 2], rank=1)
example_1.add_cells_from([[1, 3], [2, 3], [2, 4], [3, 5], [4, 5]], rank=1)

# Example 2: 2-dimensional complex
example_2 = tnx.CellComplex()
example_2.add_cell([1, 2, 3], rank=2)
example_2.add_cells_from([[2, 4, 5, 3]], rank=2)
```

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

### Create and Analyze a Cell Complex

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

Shows how to instantiate a CellComplex, dynamically add edges, and compute Hodge Laplacian matrices.

```python
import toponetx as tnx

# Instantiate a CellComplex object with a few cells
cx = tnx.CellComplex([[1, 2, 3, 4], [3, 4, 5, 6, 7, 8]], ranks=2)

# Add an edge (cell of rank 1) after initialization
cx.add_edge(0, 1)

# Compute the Hodge Laplacian matrix of dimension 1
L1 = cx.hodge_laplacian_matrix(1)

# Compute the Hodge Laplacian matrix of dimension 2
L2 = cx.hodge_laplacian_matrix(2)
```

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

### Class Documentation Template

Source: https://github.com/pyt-team/toponetx/blob/main/docs/_templates/autosummary-class-template.rst

A template for documenting classes in the TopoNetX library using Sphinx directives.

```APIDOC
## Class Documentation Template

### Description
This template is used to document classes within the TopoNetX project, automatically pulling in members, inherited members, and class methods.

### Usage
Use the following structure in your .rst files to document a class:

```rst
.. autoclass:: ClassName
   :members:
   :show-inheritance:
   :inherited-members:

   .. automethod:: __init__
```

### Components
- **autoclass**: Directive to document the class.
- **members**: Includes all members of the class.
- **show-inheritance**: Displays the inheritance hierarchy.
- **inherited-members**: Includes members inherited from parent classes.
- **automethod**: Specifically documents the constructor method.
```

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

### Get and Remove Singletons from Cell Complex

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

Extracts all singleton cells (cells of rank 1, i.e., edges) from a cell complex and then removes them. This can be useful for simplifying the complex or focusing on higher-dimensional structures.

```python
import toponetx as tnx

# Assuming 'cc' is an existing CellComplex object
singletons = cc.singletons()
cc.remove_singletons()
```

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

### Constructing and Manipulating Cell Complexes

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

Demonstrates how to initialize a CellComplex from lists or NetworkX graphs, manage cell attributes, and compute topological matrices like incidence and Hodge Laplacians.

```python
import toponetx as tnx
import networkx as nx

# Create from list of cells
c1 = tnx.Cell((1, 2, 3))
c2 = tnx.Cell((1, 2, 3, 4))
cc = tnx.CellComplex([c1, c2])

# Create from NetworkX graph
G = nx.Graph([(0, 1), (1, 2), (0, 2)])
cc = tnx.CellComplex(G)
cc.add_cells_from([[1, 2, 4], [1, 2, 7]], rank=2)

# Set and get attributes
cc.set_cell_attributes({(1, 2, 3, 4): "red"}, name="color", rank=2)
cc.set_node_attributes({1: {"label": "A"}, 2: {"label": "B"}})

# Compute matrices
B1 = cc.incidence_matrix(1)
L1 = cc.hodge_laplacian_matrix(1)
```

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

### Get Cofaces and Star from Simplicial Complex

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

Retrieves cofaces and the star of a given set of simplices. Cofaces are simplices that contain the given simplices, while the star includes all simplices that have a non-empty intersection with the given simplices.

```python
import toponetx as tnx

# Assuming 'sc' is an existing SimplicialComplex object
cofaces = sc.get_cofaces([1, 2], codimension=1)  # Cofaces of codim >= 1
star = sc.get_star([1, 2])  # All simplices containing [1, 2]
```

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

### TopoNetX Class Overview

Source: https://github.com/pyt-team/toponetx/blob/main/docs/api/classes.rst

Documentation for the core topological data structures including Atoms, Complexes, and their associated views.

```APIDOC
## TopoNetX Core Classes

### Description
This module defines the fundamental building blocks for topological networks, including atomic elements, complex structures, and view interfaces for data traversal.

### Atoms
- **Atom**: Base class for topological atoms.
- **Simplex**: Represents a simplex in a simplicial complex.
- **Path**: Represents a path in a path complex.
- **Cell**: Represents a cell in a cell complex.
- **HyperEdge**: Represents a hyperedge in a combinatorial complex.

### Complexes
- **Complex**: Base class for all topological complexes.
- **SimplicialComplex**: A collection of simplices.
- **PathComplex**: A collection of paths.
- **CellComplex**: A collection of cells.
- **CombinatorialComplex**: A general structure for hypergraphs.
- **ColoredHyperGraph**: A hypergraph with colored edges.

### Report Views
- **NodeView**, **AtomView**, **SimplexView**, **PathView**, **CellView**, **HyperEdgeView**, **ColoredHyperEdgeView**: Provide read-only or specialized views for inspecting the elements within a complex.
```

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

### Get Line Graph of Cell Complex

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

Computes the line graph of a cell complex. The line graph represents adjacencies between cells. The `s` parameter specifies the rank of cells to consider for the line graph, and `cells=True` indicates that the nodes of the line graph represent cells.

```python
import toponetx as tnx

# Assuming 'cc' is an existing CellComplex object
line_graph = cc.get_linegraph(s=1, cells=True)
```

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

### Working with Combinatorial Complexes

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

Shows how to build a CombinatorialComplex, perform skeleton filtering, and compute advanced operators like the Dirac operator.

```python
import toponetx as tnx

ccc = tnx.CombinatorialComplex()
ccc.add_cell([1, 2, 3, 4], rank=2)

# Skeleton with level filtering
rank_2_cells = ccc.skeleton(2)
upper_cells = ccc.skeleton(1, level="up")

# Compute matrices
B_0_2 = ccc.incidence_matrix(0, 2)
A = ccc.adjacency_matrix(0, via_rank=2)
D = ccc.dirac_operator_matrix()
```

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

### Get Edge Attributes and Propagate to Faces (Python)

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/01_simplicial_complexes.ipynb

Retrieves edge attributes and propagates their values to faces. First, edge attributes are fetched using `get_simplex_attributes`. Then, the dot product of these values with the transposed B2 incidence matrix (edges to faces) is computed, distributing edge data proportionally to the faces.

```python
edge_attrs = ex2_sc.get_simplex_attributes("attr")
example2_edge_values = np.array(list(edge_attrs.values()))

new_face_feature = ex2_incidence2.T.dot(example2_edge_values)

print(new_face_feature)
```

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

### Toponetx Module Overview

Source: https://github.com/pyt-team/toponetx/blob/main/docs/_templates/autosummary-module-template.rst

This section provides an overview of the Toponetx module, including its attributes, functions, classes, exceptions, and submodules.

```APIDOC
## Toponetx Module Overview

### Description
Provides a structured overview of the Toponetx module, including its attributes, functions, classes, exceptions, and submodules.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **Module Attributes**: List of module attributes.
- **Functions**: List of functions available in the module.
- **Classes**: List of classes defined within the module.
- **Exceptions**: List of exceptions that can be raised.
- **Modules**: List of submodules.

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

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

### Commit Changes

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

Steps to stage and commit your code changes locally.

```bash
$ git add <modified_files>
$ git commit -m "Add my feature"
```

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

### Constructing a Combinatorial Complex

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/03_combinatorial_complexes.ipynb

Demonstrates how to initialize a CombinatorialComplex object and populate it with cells of different ranks using the add_cell method.

```python
example = tnx.CombinatorialComplex()
example.add_cell([1, 2], rank=1)
print(example)
example.add_cell([1, 3], rank=1)
print(example)
example.add_cell([1, 2, 4, 3], rank=2)
print(example)
example.add_cell([2, 5], rank=1)
print(example)
example.add_cell([2, 6, 4], rank=2)
print(example)
```

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

### TopoNetX Modules Overview

Source: https://github.com/pyt-team/toponetx/blob/main/docs/api/index.rst

This section provides an overview of the main modules available in the TopoNetX library.

```APIDOC
## TopoNetX API Reference

This API reference gives an overview of ``TopoNetX``, which consists of several modules:

- ``classes``: Implements the topological domains, e.g., :py:class:`SimplicialComplex <toponetx.SimplicialComplex>`, :py:class:`CellComplex <toponetx.CellComplex>`, :py:class:`CombinatorialComplex <toponetx.CombinatorialComplex>`.
- ``datasets``: Implements utilities to load small datasets on topological domains.
- ``transform``: Implements functions to transform the topological domain that supports a dataset, effectively "lifting" the dataset onto another domain.
- ``algorithms``: Implements signal processing techniques on topological domains, such as the eigendecomposition of a laplacian.
- ``generators``: Implements functions to generate random topological domains.
- ``readwrite``: Implements functions to read and write topological domains from and to disk.

### Modules

- **classes**: Defines core topological domain structures.
- **datasets**: Utilities for loading topological datasets.
- **transform**: Functions for transforming topological domains.
- **algorithms**: Signal processing algorithms for topological domains.
- **generators**: Functions for creating random topological domains.
- **readwrite**: I/O functions for topological domains.
```

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

### Create and List Simplicial Complex from Edges

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/01_simplicial_complexes.ipynb

Demonstrates how to define a simplicial complex using an edge set and retrieve the list of all simplices contained within the complex.

```python
edge_set = [[1, 2], [2, 3], [2, 4], [3, 4], [2, 5], [5, 6], [5, 7], [6, 7]]
ex1_sc = tnx.SimplicialComplex(edge_set)
ex1_sc.simplices
```

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

### Create and Analyze a Combinatorial Complex

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

Illustrates the creation of a CombinatorialComplex, adding cells of varying ranks, and computing incidence matrices between specific ranks.

```python
import toponetx as tnx

# Instantiate a combinatorial complex object with a few cells
cc = tnx.CombinatorialComplex()

# Add some cells of different ranks after initialization
cc.add_cell([1, 2, 3], rank=2)
cc.add_cell([3, 4, 5], rank=2)
cc.add_cells_from([[2, 3, 4, 5], [3, 4, 5, 6, 7]], ranks=3)

# Compute the incidence matrix between cells of rank 0 and 2
B02 = cc.incidence_matrix(0, 2)

# Compute the incidence matrix between cells of rank 0 and 3
B03 = cc.incidence_matrix(0, 3)
```

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

### Create and Manipulate Simplicial Complexes in Python

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

Demonstrates the creation, dynamic modification, and attribute management of SimplicialComplex objects in TopoNetX. It covers initialization from lists or NetworkX graphs, adding/removing simplices, accessing skeletons, and setting/getting simplex attributes. Compatible with NetworkX.

```python
import toponetx as tnx
import networkx as nx

# Create a simplicial complex from maximal simplices
sc = tnx.SimplicialComplex([[1, 2, 3], [2, 3, 5], [0, 1]])

# Access basic properties
print(f"Shape: {sc.shape}")  # (5, 5, 2) - counts of 0, 1, 2-simplices
print(f"Dimension: {sc.dim}")  # 2
print(f"Simplices: {sc.simplices}")

# Add simplices dynamically
sc.add_simplex([3, 4, 5], weight=2.0)
sc.add_simplices_from([[5, 6], [6, 7, 8]])

# Get skeleton at a specific dimension
edges = sc.skeleton(1)  # All 1-simplices (edges)
triangles = sc.skeleton(2)  # All 2-simplices (triangles)

# Create from NetworkX graph (preserves attributes)
G = nx.Graph()
G.add_edge(0, 1, weight=4)
G.add_edges_from([(0, 3), (0, 4), (1, 4)])
sc_from_graph = tnx.SimplicialComplex(simplices=G)
print(sc_from_graph[(0, 1)]["weight"])  # 4

# Set and get simplex attributes
sc.set_simplex_attributes({(1, 2, 3): "red", (2, 3, 5): "blue"}, name="color")
print(sc[(1, 2, 3)]["color"])  # 'red'
colors = sc.get_simplex_attributes("color")

# Check if simplex is maximal
print(sc.is_maximal([1, 2, 3]))  # True if not face of any other simplex

# Get maximal simplices
maximal = list(sc.get_all_maximal_simplices())

```

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

### Create and Manipulate Cell Complexes in Python

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

Shows how to construct and interact with CellComplex objects in TopoNetX, supporting 2D complexes with regular and non-regular cells. Demonstrates iterative cell addition and accessing basic properties like shape, nodes, edges, and cells.

```python
import toponetx as tnx
import networkx as nx

# Create a cell complex iteratively
cc = tnx.CellComplex()
cc.add_cell([1, 2, 3, 4], rank=2)  # 4-sided cell
cc.add_cell([2, 3, 4, 5], rank=2)  # Another 4-sided cell
cc.add_cell([5, 6, 7, 8], rank=2)
cc.add_edge(1, 9)  # Add a standalone edge

# Access properties
print(f"Shape: {cc.shape}")  # (nodes, edges, 2-cells)
print(f"Nodes: {list(cc.nodes)}")
print(f"Edges: {list(cc.edges)}")
print(f"Cells: {cc.cells}")

```

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

### Graph Transformations to Simplicial Complexes

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

Illustrates how to transform NetworkX graphs into simplicial complexes using clique, neighbor, and Vietoris-Rips complexes.

```APIDOC
## Graph Transformations

### Description
TopoNetX provides functions to transform graphs into simplicial complexes using various methods including clique complexes, neighbor complexes, and Vietoris-Rips complexes.

### Method
N/A (Illustrative Code Examples)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Clique complex: every clique becomes a simplex
```python
G = nx.karate_club_graph()
sc_clique = tnx.graph_to_clique_complex(G)
print(f"Clique complex dimension: {sc_clique.dim}")
```

## Clique complex with maximum dimension
```python
sc_clique_2d = tnx.graph_to_clique_complex(G, max_rank=2)
```

## Neighbor complex: each node's neighborhood forms a simplex
```python
sc_neighbor = tnx.graph_to_neighbor_complex(G)
print(f"Neighbor complex shape: {sc_neighbor.shape}")
```
```

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

### Load Built-in Datasets

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

Accesses standard mesh datasets like the Stanford Bunny, SHREC 16, and COSEG for topological deep learning experiments.

```python
import toponetx as tnx

sc_bunny = tnx.datasets.stanford_bunny("simplicial")
train_data, test_data = tnx.datasets.shrec_16(size="small")
coseg_data = tnx.datasets.coseg("alien")
```

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

### Mesh Loading and Format Conversion

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

Loads 3D meshes from files and converts between TopoNetX complexes, trimesh objects, and other graph-based representations.

```python
import toponetx as tnx
import trimesh

sc = tnx.SimplicialComplex.load_mesh("path/to/mesh.obj")
mesh = trimesh.Trimesh(vertices=[[0, 0, 0], [0, 0, 1], [0, 1, 0], [1, 0, 0]], faces=[[0, 1, 2], [0, 1, 3], [0, 2, 3], [1, 2, 3]], process=False)
sc = tnx.SimplicialComplex.from_trimesh(mesh)
mesh_back = sc.to_trimesh(vertex_position_name="position")
cell_cx = sc.to_cell_complex()
hg = sc.to_hypergraph()
```

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

### Hodge Laplacian Spectrum Analysis

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

Explains how to compute and utilize Hodge Laplacian spectra for spectral analysis of topological structures in simplicial, cell, and combinatorial complexes.

```APIDOC
## Hodge Laplacian Spectrum

### Description
TopoNetX provides functions for computing eigenvalues and eigenvectors of Hodge Laplacian matrices, which are essential for spectral analysis of topological structures.

### Method
N/A (Illustrative Code Examples)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Compute Hodge Laplacian spectrum for a simplicial complex
```python
sc = tnx.SimplicialComplex([[1, 2, 3], [2, 3, 5], [0, 1]])

L1 = sc.hodge_laplacian_matrix(1)
spectrum = tnx.simplicial_complex_hodge_laplacian_spectrum(sc, rank=1)
print(f"Eigenvalues: {spectrum}")
```

## Compute eigenvectors
```python
eigenvalues, eigenvectors = tnx.hodge_laplacian_eigenvectors(L1, n_components=3)
print(f"First 3 eigenvalues: {eigenvalues}")
print(f"Eigenvector shape: {eigenvectors.shape}")
```

## Set eigenvectors as simplex attributes
```python
tnx.set_hodge_laplacian_eigenvector_attrs(
    sc,
    dim=1,
    n_components=2,
    laplacian_type="hodge",  # Options: "up", "down", "hodge"
    normalized=True
)
# Access computed eigenvectors
vec0 = sc.get_simplex_attributes("0.th_eigen", rank=1)
```

## Cell complex spectrum
```python
cc = tnx.CellComplex()
cc.add_cell([1, 2, 3, 4], rank=2)
cc.add_cell([2, 3, 4, 5], rank=2)
cc_spectrum = tnx.cell_complex_hodge_laplacian_spectrum(cc, rank=1)
```

## Adjacency spectrum
```python
cc_adj_spectrum = tnx.cell_complex_adjacency_spectrum(cc, rank=1)
```

## Combinatorial complex spectrum
```python
ccc = tnx.CombinatorialComplex(cells=[[1, 2, 3], [2, 3], [0]], ranks=[2, 1, 0])
ccc_spectrum = tnx.combinatorial_complex_adjacency_spectrum(ccc, rank=0, via_rank=2)
```
```

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

### Compute Incidence Matrix for Combinatorial Complexes

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/03_combinatorial_complexes.ipynb

Demonstrates how to generate incidence matrices between different ranks of cells in a combinatorial complex using the incidence_matrix method. The output is converted to a dense matrix format for easier inspection.

```python
B01 = example.incidence_matrix(0, 1).todense()
print(B01)

B02 = example.incidence_matrix(0, 2).todense()
print(B02)

B12 = example.incidence_matrix(1, 2).todense()
print(B12)
```

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

### Synchronize Main Branch with Upstream

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

Commands to update your local main branch with the latest changes from the upstream repository.

```bash
$ git checkout main
$ git pull upstream main
```

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

### Generate Random Simplicial Complexes

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

Demonstrates the generation of random topological structures including Linial-Meshulam and random clique complexes for statistical analysis.

```python
import toponetx as tnx

sc_lm = tnx.linial_meshulam_complex(n=10, p=0.5, seed=42)
sc_clique = tnx.random_clique_complex(n=15, p=0.3, seed=42)
sc_multi = tnx.multiparameter_linial_meshulam_complex(n=12, ps=[0.8, 0.5, 0.3], seed=42)
samples = [tnx.random_clique_complex(20, 0.25, seed=i) for i in range(10)]
```

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

### Run All Tests

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

Command to execute all tests in the test directory using pytest.

```bash
$ pytest test/
```

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

### Display Simplicial Complex Visualization

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/01_simplicial_complexes.ipynb

Uses IPython to render an image file representing a simplicial complex structure.

```python
from IPython.display import Image
Image("sc.png")
```

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

### Assign Features to Simplex Attributes in Python

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/01_simplicial_complexes.ipynb

Demonstrates how to assign data or 'features' to faces, edges, and vertices using the `set_simplex_attributes` function in Toponetx.

```python
# Example usage of set_simplex_attributes function
# (Actual code implementation not provided in the input text)
```

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

### Generate and Print B01 Incidence Matrix

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/03_combinatorial_complexes.ipynb

This snippet demonstrates how to generate the incidence matrix between rank-0 and rank-1 cells and prints its dense representation.

```APIDOC
## Generate and Print B01 Incidence Matrix

### Description
Generates the incidence matrix between rank-0 and rank-1 cells and displays its dense format.

### Method
`example.incidence_matrix(0, 1).todense()`

### Endpoint
N/A (This is a library function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
B01 = example.incidence_matrix(0, 1).todense()
print(B01)
```

### Response
#### Success Response (200)
- **B01** (numpy.ndarray) - The dense representation of the incidence matrix between rank-0 and rank-1 cells.

#### Response Example
```
[[1 1 0]
 [1 0 1]
 [0 1 0]
 [0 0 0]
 [0 0 1]
 [0 0 0]]
```
```

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

### Cite TopoNetX and Topological Deep Learning

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

BibTeX citation for the foundational paper on Topological Deep Learning.

```BibTeX
@misc{hajij2023topological,
      title={Topological Deep Learning: Going Beyond Graph Data},
      author={Mustafa Hajij and Ghada Zamzmi and Theodore Papamarkou and Nina Miolane and Aldo Guzmán-Sáenz and Karthikeyan Natesan Ramamurthy and Tolga Birdal and Tamal K. Dey and Soham Mukherjee and Shreyas N. Samaga and Neal Livesay and Robin Walters and Paul Rosen and Michael T. Schaub},
      year={2023},
      eprint={2206.00606},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}
```

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

### Create Feature Branch

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

Command to create a new branch for developing new features or fixes.

```bash
$ git checkout -b <branch-name>
```

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

### Generic Docstring Template

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

A template illustrating the standard structure for documenting a Python method.

```APIDOC
## def my_method(self, my_param_1, my_param_2="vector")

### Description
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
#### Parameters
- **my_param_1** (array-like, shape=[..., dim]) - Required - Write a short description of parameter my_param_1.
- **my_param_2** (str, {"vector", "matrix"}) - Optional - Write a short description of parameter my_param_2. Optional, default: "vector".

### Returns
#### 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.

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

### References
If relevant, provide a reference with associated pdf or
wikipedia page.
```

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

### Compute Algebraic Matrices for Simplicial Complexes in Python

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

Illustrates the computation of incidence, Hodge Laplacian, adjacency, and Dirac operator matrices for SimplicialComplex objects in TopoNetX. Supports signed/unsigned matrices and indexed outputs. These are crucial for topological data analysis.

```python
import toponetx as tnx

sc = tnx.SimplicialComplex([[1, 2, 3, 4], [3, 4, 8]])

# Compute incidence (boundary) matrices
B1 = sc.incidence_matrix(1)  # Boundary from 1-simplices to 0-simplices
B2 = sc.incidence_matrix(2)  # Boundary from 2-simplices to 1-simplices

# Get indices along with matrices
row_idx, col_idx, B1_indexed = sc.incidence_matrix(1, index=True)
print(f"Row indices (0-simplices): {row_idx}")
print(f"Column indices (1-simplices): {col_idx}")

# Unsigned incidence matrix
B1_unsigned = sc.incidence_matrix(1, signed=False)

# Hodge Laplacian matrices
L0 = sc.hodge_laplacian_matrix(0)  # Graph Laplacian
L1 = sc.hodge_laplacian_matrix(1)  # 1-Hodge Laplacian
L2 = sc.hodge_laplacian_matrix(2)  # 2-Hodge Laplacian

# Up and Down Laplacians
L1_up = sc.up_laplacian_matrix(1)
L1_down = sc.down_laplacian_matrix(1)

# Adjacency and coadjacency matrices
A1 = sc.adjacency_matrix(1)  # Edge adjacency
coA2 = sc.coadjacency_matrix(2)  # Face coadjacency

# Normalized Laplacian
L1_norm = sc.normalized_laplacian_matrix(1)

# Dirac operator matrix (combines all boundary operators)
D = sc.dirac_operator_matrix()
idx, D_indexed = sc.dirac_operator_matrix(index=True)

# Coincidence (coboundary) matrix
coB1 = sc.coincidence_matrix(1)  # Transpose of B1

```

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

### Compute and Print Incidence Matrix B01 (Python)

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/04_colored_hypergraphs.ipynb

Generates and displays the incidence matrix B01, showing the relationship between 0-cells and 1-cells. An entry of 1 indicates that a 0-cell is contained within a 1-cell.

```python
B01 = example.incidence_matrix(0, 1).todense()
print(B01)
```

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

### Displaying a Cell Complex Image in Python

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/02_cell_complexes.ipynb

This snippet demonstrates how to import necessary libraries and display an image representing a cell complex. It's useful for visualizing the structure of cell complexes.

```python
from IPython.display import Image

import toponetx as tnx

Image("cc.png")
```

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

### Push Changes to Fork

Source: https://github.com/pyt-team/toponetx/blob/main/docs/project/contributing.rst

Command to push your committed changes to your remote fork.

```bash
$ git push origin <branch-name>
```

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

### Generate and Print Incidence Matrix (Python)

Source: https://github.com/pyt-team/toponetx/blob/main/tutorials/04_colored_hypergraphs.ipynb

This Python code generates the incidence matrix between 1-cells and 2-cells using the `incidence_matrix` function from the `toponetx` library. The resulting dense matrix is then printed to the console. This matrix is crucial for understanding the connectivity and structure of higher-order topological data.

```python
B12 = example.incidence_matrix(1, 2).todense()
print(B12)
```