🌐 TopoNetX (TNX) 🍩

Computing with Relational Data abstracted as Topological Domains

Many complex systems, ranging from socio-economic systems such as social networks, over to biological systems (e.g., proteins) and technical systems can be abstracted as a set of entities with are linked to each other via a set of relations. For instance, a social network may be abstracted as a set vertices corresponding to people linked via various social interactions, including pairwise relationships such as friendships and higher-order relationships involving multiple people. This relational data can be abstracted as a topological domain such as a graph, hypergraph, simplicial, cellular or combinatorial complex, which enables the principled analysis of such data.

TopoNetX provides a unified platform to compute with such relational data.

🎯 Scope and functionality

TopoNetX (TNX) is a package for computing with topological domains and studying their properties.

With its dynamic construction capabilities and support for arbitrary attributes and data, TopoNetX allows users to easily explore the topological structure of their data and gain insights into its underlying geometric and algebraic properties.

Available functionality ranges from computing boundary operators and Hodge Laplacians on simplicial/cell/combinatorial complexes to performing higher-order adjacency calculations.

TNX is similar to NetworkX, a popular graph package, and extends its capabilities to support a wider range of mathematical structures, including cell complexes, simplicial complexes and combinatorial complexes. The TNX library provides classes and methods for modeling the entities and relations found in higher-order networks such as simplicial, cellular, CW and combinatorial complexes. This package serves as a repository of the methods and algorithms we find most useful as we explore the knowledge that can be encoded via higher-order networks.

TNX supports the construction of many topological structures including the CellComplex, SimplicialComplex and CombinatorialComplex classes. These classes provide methods for computing boundary operators, Hodge Laplacians and higher-order adjacency operators on cell, simplicial and combinatorial complexes, respectively. The classes are used in many areas of mathematics and computer science, such as algebraic topology, geometry, and data analysis.

TNX is developed by the pyt-team

🛠️ Main features

1. Dynamic construction of cell, simplicial and combinatorial complexes, allowing users to add or remove objects from these structures after their initial creation.
2. Compatibility with the NetworkX and gudhi packages, enabling users to leverage the powerful algorithms and data structures provided by these packages.
3. Support for attaching arbitrary attributes and data to cells, simplices and other entities in a complex, allowing users to store and manipulate a versatile range of information about these objects.
4. Computation of boundary operators, Hodge Laplacians and higher-order adjacency operators on a complex, enabling users to study the topological properties of the space.
5. Robust error handling and validation of input data, ensuring that the package is reliable and easy to use.
6. Package dependencies are kept to a minimum, to facilitate easy installation and to reduce future installation issues arising from such dependencies.

🤖 Installing TopoNetX

1. Clone a copy of TopoNetX from source:

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

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

git pull

3. Install TopoNetX in editable mode (requires pip ≥ 21.3 for PEP 660 support):

pip install -e '.[all]'

4. Install pre-commit hooks:

pre-commit install

🦾 Getting Started

Example 1: creating a simplicial complex

from toponetx.classes import SimplicialComplex

# Instantiate a SimplicialComplex object with a few simplices

sc = 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 2: creating a cell complex

from toponetx.classes import CellComplex

# Instantiate a CellComplex object with a few cells

cx = 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)

Example 3: creating a combinatorial complex

from toponetx.classes import CombinatorialComplex

# Instantiate a combinatorial complex object with a few cells

cc = 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)

🔍 References

To learn more about topological domains, and how they can be used in deep learning:

• Mustafa Hajij, Ghada Zamzmi, Theodore Papamarkou, Nina Miolane, Aldo Guzmán-Sáenz, Karthikeyan Natesan Ramamurthy, Tolga Birdal, Tamal K. Dey, Soham Mukherjee, Shreyas N. Samaga, Neal Livesay, Robin Walters, Paul Rosen, Michael T. Schaub. Topological Deep Learning: Going Beyond Graph Data.

@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}
}

• Mathilde Papillon, Sophia Sanborn, Mustafa Hajij, Nina Miolane. Architectures of Topological Deep Learning: A Survey on Topological Neural Networks.

@misc{papillon2023architectures,
      title={Architectures of Topological Deep Learning: A Survey on Topological Neural Networks},
      author={Mathilde Papillon and Sophia Sanborn and Mustafa Hajij and Nina Miolane},
      year={2023},
      eprint={2304.10031},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

⭐ Acknowledgements

TopoNetX has been built with the help of several open-source packages. All of these are listed in setup.py. Some of these packages include:

• NetworkX
• HyperNetX
• gudhi
• trimesh