{"id":13476668,"url":"https://github.com/pyt-team/TopoNetX","last_synced_at":"2025-03-27T03:30:39.895Z","repository":{"id":154180205,"uuid":"523084160","full_name":"pyt-team/TopoNetX","owner":"pyt-team","description":"Computing on Topological Domains","archived":false,"fork":false,"pushed_at":"2025-03-20T18:24:39.000Z","size":6153,"stargazers_count":207,"open_issues_count":11,"forks_count":43,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-20T19:56:31.261Z","etag":null,"topics":["cell-complex-neural-networks","cell-complexes","cellular-complex","combinatorial-complex","cw-complex","cw-complex-networks","cw-networks","heterogeneous-hypergraph","higher-order-message-passing","higher-order-networks","hypergraph-neural-networks","simplicial-complex","simplicial-neural-networks","tensor-diagrams","topological-data-analysis","topological-deep-learning","topological-learning","topological-message-passing","topological-neural-networks"],"latest_commit_sha":null,"homepage":"https://pyt-team.github.io/toponetx/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyt-team.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-09T19:32:27.000Z","updated_at":"2025-03-20T07:39:06.000Z","dependencies_parsed_at":"2023-11-27T14:46:20.826Z","dependency_job_id":"2fd7e5f2-679e-4801-8a5f-98cfb6901838","html_url":"https://github.com/pyt-team/TopoNetX","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyt-team%2FTopoNetX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyt-team%2FTopoNetX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyt-team%2FTopoNetX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyt-team%2FTopoNetX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyt-team","download_url":"https://codeload.github.com/pyt-team/TopoNetX/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245778315,"owners_count":20670682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cell-complex-neural-networks","cell-complexes","cellular-complex","combinatorial-complex","cw-complex","cw-complex-networks","cw-networks","heterogeneous-hypergraph","higher-order-message-passing","higher-order-networks","hypergraph-neural-networks","simplicial-complex","simplicial-neural-networks","tensor-diagrams","topological-data-analysis","topological-deep-learning","topological-learning","topological-message-passing","topological-neural-networks"],"created_at":"2024-07-31T16:01:33.190Z","updated_at":"2025-03-27T03:30:39.208Z","avatar_url":"https://github.com/pyt-team.png","language":"Jupyter Notebook","funding_links":[],"categories":["Jupyter Notebook"],"sub_categories":[],"readme":"\u003ch2 align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/pyt-team/TopoNetX/main/resources/logo.png\" height=\"250\"\u003e\n\u003c/h2\u003e\n\n\u003ch3 align=\"center\"\u003e\n   Computing with Relational Data Abstracted as Topological Domains\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-scope-and-functionality\"\u003eScope and Functionality\u003c/a\u003e •\n  \u003ca href=\"#%EF%B8%8F-main-features\"\u003eMain Features\u003c/a\u003e •\n  \u003ca href=\"#-installing-toponetx\"\u003eInstalling TopoNetX\u003c/a\u003e •\n  \u003ca href=\"#-getting-started\"\u003eGetting Started\u003c/a\u003e •\n  \u003ca href=\"#-references\"\u003eReferences\u003c/a\u003e •\n  \u003ca href=\"#-acknowledgements\"\u003eAcknowledgements\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Test](https://github.com/pyt-team/TopoNetX/actions/workflows/test.yml/badge.svg)](https://github.com/pyt-team/TopoNetX/actions/workflows/test.yml)\n[![Lint](https://github.com/pyt-team/TopoNetX/actions/workflows/lint.yml/badge.svg)](https://github.com/pyt-team/TopoNetX/actions/workflows/lint.yml)\n[![Codecov](https://codecov.io/gh/pyt-team/TopoNetX/branch/main/graph/badge.svg)](https://app.codecov.io/gh/pyt-team/TopoNetX)\n[![Docs](https://img.shields.io/badge/docs-website-brightgreen)](https://pyt-team.github.io/toponetx/index.html)\n[![Python](https://img.shields.io/badge/python-3.10+-blue?logo=python)](https://www.python.org/)\n[![license](https://badgen.net/github/license/pyt-team/TopoNetX?color=green)](https://github.com/pyt-team/TopoNetX/blob/main/LICENSE)\n[![slack](https://img.shields.io/badge/chat-on%20slack-purple?logo=slack)](https://join.slack.com/t/pyt-teamworkspace/shared_invite/zt-2k63sv99s-jbFMLtwzUCc8nt3sIRWjEw)\n\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7958504.svg)](https://doi.org/10.5281/zenodo.7958504)\n\n\u003c/div\u003e\n\n![toponetx](https://user-images.githubusercontent.com/8267869/234068354-af9480f1-1d18-4914-92f1-916d9093e44d.png)\n\nMany 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.\nFor 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.\nThis _relational data_ can be abstracted as a topological domain such as a graph, hypergraph, simplicial, cellular path or combinatorial complex, which enables the principled analysis of such data.\n\n`TopoNetX` provides a unified platform to compute with such relational data.\n\n## 🎯 Scope and functionality\n\n`TopoNetX` (TNX) is a package for computing with topological domains and studying their properties.\n\nWith its dynamic construction capabilities and support for arbitrary\nattributes and data, `TopoNetX` allows users to easily explore the topological structure\nof their data and gain insights into its underlying geometric and algebraic properties.\n\nAvailable functionality ranges\nfrom computing boundary operators and Hodge Laplacians on simplicial/cell/combinatorial complexes\nto performing higher-order adjacency calculations.\n\nTNX is similar to [`NetworkX`](https://networkx.org/), a popular graph package, and extends its capabilities to support a\nwider range of mathematical structures, including cell complexes, simplicial complexes and\ncombinatorial complexes.\nThe TNX library provides classes and methods for modeling the entities and relations\nfound in higher-order networks such as simplicial, cellular, CW and combinatorial complexes.\nThis package serves as a repository of the methods and algorithms we find most useful\nas we explore the knowledge that can be encoded via higher-order networks.\n\nTNX supports the construction of many topological structures including the `CellComplex`, `PathComplex`, \"ColoredHyperGraph\" `SimplicialComplex` and `CombinatorialComplex` classes.\nThese classes provide methods for computing boundary operators, Hodge Laplacians\nand higher-order adjacency operators on cell, simplicial and combinatorial complexes,\nrespectively. The classes are used in many areas of mathematics and computer science,\nsuch as algebraic topology, geometry, and data analysis.\n\nTNX is developed by the [pyt-team](https://github.com/pyt-team)\n\n## 🛠️ Main features\n\n1. Dynamic construction of cell, simplicial and combinatorial complexes, allowing users to add or remove objects from these structures after their initial creation.\n2. Compatibility with the [`NetworkX`](https://networkx.org/) and [`gudhi`](https://gudhi.inria.fr/) packages, enabling users to\n   leverage the powerful algorithms and data structures provided by these packages.\n3. 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.\n4. Computation of boundary operators, Hodge Laplacians and higher-order adjacency\n   operators on a complex, enabling users to study the topological properties of the space.\n5. Robust error handling and validation of input data, ensuring that the package is\n   reliable and easy to use.\n6. Package dependencies are kept to a minimum,\n   to facilitate easy installation and\n   to reduce future installation issues arising from such dependencies.\n\n# 🤖 Installing TopoNetX\n\n`TopoNetX` is available on PyPI and can be installed using `pip`:\n\n```bash\npip install toponetx\n```\n\n# 🦾 Getting Started\n\n## Example 1: creating a simplicial complex\n\n```python\nimport toponetx as tnx\n\n# Instantiate a SimplicialComplex object with a few simplices\nsc = tnx.SimplicialComplex([[1, 2, 3], [2, 3, 4], [0, 1]])\n\n# Compute the incidence matrix between 1-skeleton and 0-skeleton\nB1 = sc.incidence_matrix(1)\n\n# Compute the incidence matrix between 2-skeleton and 1-skeleton\nB2 = sc.incidence_matrix(2)\n```\n\n## Example 2: creating a cell complex\n\n```python\nimport toponetx as tnx\n\n# Instantiate a CellComplex object with a few cells\ncx = tnx.CellComplex([[1, 2, 3, 4], [3, 4, 5, 6, 7, 8]], ranks=2)\n\n# Add an edge (cell of rank 1) after initialization\ncx.add_edge(0, 1)\n\n# Compute the Hodge Laplacian matrix of dimension 1\nL1 = cx.hodge_laplacian_matrix(1)\n\n# Compute the Hodge Laplacian matrix of dimension 2\nL2 = cx.hodge_laplacian_matrix(2)\n```\n\n## Example 3: creating a combinatorial complex\n\n```python\nimport toponetx as tnx\n\n# Instantiate a combinatorial complex object with a few cells\ncc = tnx.CombinatorialComplex()\n\n# Add some cells of different ranks after initialization\ncc.add_cell([1, 2, 3], rank=2)\ncc.add_cell([3, 4, 5], rank=2)\ncc.add_cells_from([[2, 3, 4, 5], [3, 4, 5, 6, 7]], ranks=3)\n\n# Compute the incidence matrix between cells of rank 0 and 2\nB02 = cc.incidence_matrix(0, 2)\n\n# Compute the incidence matrix between cells of rank 0 and 3\nB03 = cc.incidence_matrix(0, 3)\n```\n\n## 🧑‍💻 Install from source\n\nTo install the latest version from source, follow these steps:\n\n1. Clone a copy of `TopoNetX` from source:\n\n```bash\ngit clone https://github.com/pyt-team/TopoNetX\ncd TopoNetX\n```\n\n2. If you have already cloned `TopoNetX` from source, update it:\n\n```bash\ngit pull\n```\n\n3. Install `TopoNetX` in editable mode (requires `pip` ≥ 21.3 for [PEP 660](https://peps.python.org/pep-0610/) support):\n\n```bash\npip install -e '.[all]'\n```\n\n4. Install pre-commit hooks:\n\n```bash\npre-commit install\n```\n\n## 🔍 References\n\nTopoNetX is a part of TopoX, a suite of Python packages for machine learning on topological domains. If you find TopoNetX useful please consider citing our software paper:\n\n- Hajij et al. 2023. [TopoX: a suite of Python packages for machine learning on topological domains](https://arxiv.org/abs/2402.02441)\n\n```\n@article{hajij2024topox,\n  title={TopoX: A Suite of Python Packages for Machine Learning on Topological Domains},\n  author={PYT-Team},\n  journal={arXiv preprint arXiv:2402.02441},\n  year={2024}\n}\n```\n\nTo learn more about topological domains, and how they can be used in deep learning:\n\n- 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](https://arxiv.org/abs/2206.00606) (arXiv) • [Topological Deep Learning: A Book](https://tdlbook.org/)\n\n```\n@misc{hajij2023topological,\n      title={Topological Deep Learning: Going Beyond Graph Data},\n      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},\n      year={2023},\n      eprint={2206.00606},\n      archivePrefix={arXiv},\n      primaryClass={cs.LG}\n}\n```\n\n- Mathilde Papillon, Sophia Sanborn, Mustafa Hajij, Nina Miolane. [Architectures of Topological Deep Learning: A Survey on Topological Neural Networks.](https://arxiv.org/pdf/2304.10031.pdf)\n\n```\n@misc{papillon2023architectures,\n      title={Architectures of Topological Deep Learning: A Survey on Topological Neural Networks},\n      author={Mathilde Papillon and Sophia Sanborn and Mustafa Hajij and Nina Miolane},\n      year={2023},\n      eprint={2304.10031},\n      archivePrefix={arXiv},\n      primaryClass={cs.LG}\n}\n```\n\n# ⭐ Acknowledgements\n\n`TopoNetX` has been built with the help of several open-source packages.\nAll of these are listed in setup.py.\nSome of these packages include:\n\n- [`NetworkX`](https://networkx.org/)\n- [`HyperNetX`](https://pnnl.github.io/HyperNetX/)\n- [`gudhi`](https://gudhi.inria.fr/python/latest/)\n- [`trimesh`](https://trimsh.org/index.html)\n\n## Funding\n\n\u003cimg align=\"right\" width=\"200\" src=\"https://raw.githubusercontent.com/pyt-team/TopoNetX/main/resources/erc_logo.png\"\u003e\n\nPartially funded by the European Union (ERC, HIGH-HOPeS, 101039827). Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council Executive Agency. Neither the European Union nor the granting authority can be held responsible for them.\n\nPartially funded by the National Science Foundation (DMS-2134231, DMS-2134241).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyt-team%2FTopoNetX","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyt-team%2FTopoNetX","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyt-team%2FTopoNetX/lists"}