<h2 align="center"> <img src="https://yellow-cdn.veclightyear.com/ab5030c0/24bce066-fbdd-45e3-a1f9-220ba0425537.png" height="250"> </h2> <h3 align="center"> 将关系数据抽象为拓扑域进行计算 </h3> <p align="center"> <a href="#-范围和功能">范围和功能</a> • <a href="#%EF%B8%8F-主要特性">主要特性</a> • <a href="#-安装-toponetx">安装 TopoNetX</a> • <a href="#-入门指南">入门指南</a> • <a href="#-参考文献">参考文献</a> • <a href="#-致谢">致谢</a> </p> <div align="center">

</div>

许多复杂系统，从社会经济系统（如社交网络）到生物系统（如蛋白质）和技术系统，都可以抽象为一组通过一系列关系相互连接的实体。例如，社交网络可以抽象为一组代表人的顶点，这些顶点通过各种社交互动相连，包括双人关系（如朋友关系）和涉及多人的高阶关系。这种关系数据可以抽象为图、超图、单纯复形、细胞路径或组合复形等拓扑域，从而实现对这类数据的系统分析。

TopoNetX 提供了一个统一的平台来处理这种关系数据。

🎯 范围和功能

TopoNetX（TNX）是一个用于对拓扑域进行计算并研究其性质的软件包。

凭借其动态构建能力以及对任意属性和数据的支持，TopoNetX 使用户能够轻松探索数据的拓扑结构，并深入了解其底层几何和代数特性。

可用功能范围从计算单纯复形/细胞复形/组合复形上的边界算子和霍奇拉普拉斯算子，到执行高阶邻接计算。

TNX 与流行的图包 NetworkX 类似，并扩展了其功能以支持更广泛的数学结构，包括细胞复形、单纯复形和组合复形。TNX 库提供了用于建模高阶网络（如单纯复形、细胞复形、CW复形和组合复形）中实体和关系的类和方法。这个包作为我们在探索可通过高阶网络编码的知识时发现的最有用方法和算法的存储库。

TNX 支持构建多种拓扑结构，包括 CellComplex、PathComplex、"ColoredHyperGraph" SimplicialComplex 和 CombinatorialComplex 类。这些类提供了计算细胞复形、单纯复形和组合复形上的边界算子、霍奇拉普拉斯算子和高阶邻接算子的方法。这些类在数学和计算机科学的许多领域都有应用，如代数拓扑、几何和数据分析。

TNX 由 pyt-team 开发。

🛠️ 主要特性

1. 动态构建细胞复形、单纯复形和组合复形，允许用户在初始创建后添加或删除这些结构中的对象。
2. 与 NetworkX 和 gudhi 包兼容，使用户能够利用这些包提供的强大算法和数据结构。
3. 支持为复形中的细胞、单纯形和其他实体附加任意属性和数据，允许用户存储和操作这些对象的多种信息。
4. 计算复形上的边界算子、霍奇拉普拉斯算子和高阶邻接算子，使用户能够研究空间的拓扑特性。
5. 强大的错误处理和输入数据验证，确保包的可靠性和易用性。
6. 尽量减少包的依赖项，以便于安装并减少未来因依赖项而产生的安装问题。

🤖 安装 TopoNetX

TopoNetX 可在 PyPI 上获得，可以使用 pip 安装：

pip install toponetx

🦾 入门指南

示例 1：创建单纯复形

import toponetx as tnx

# 实例化一个 SimplicialComplex 对象，包含几个单纯形
sc = tnx.SimplicialComplex([[1, 2, 3], [2, 3, 4], [0, 1]])

# 计算 1-骨架和 0-骨架之间的关联矩阵
B1 = sc.incidence_matrix(1)

# 计算 2-骨架和 1-骨架之间的关联矩阵
B2 = sc.incidence_matrix(2)

示例 2：创建细胞复形

import toponetx as tnx
# 实例化一个包含几个单元的CellComplex对象
cx = tnx.CellComplex([[1, 2, 3, 4], [3, 4, 5, 6, 7, 8]], ranks=2)

# 初始化后添加一条边（1维单元）
cx.add_edge(0, 1)

# 计算1维Hodge拉普拉斯矩阵
L1 = cx.hodge_laplacian_matrix(1)

# 计算2维Hodge拉普拉斯矩阵
L2 = cx.hodge_laplacian_matrix(2)

示例3：创建组合复形

import toponetx as tnx

# 实例化一个包含几个单元的组合复形对象
cc = tnx.CombinatorialComplex()

# 初始化后添加不同维度的单元
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)

# 计算0维和2维单元之间的关联矩阵
B02 = cc.incidence_matrix(0, 2)

# 计算0维和3维单元之间的关联矩阵
B03 = cc.incidence_matrix(0, 3)

🧑‍💻 从源代码安装

要从源代码安装最新版本，请按以下步骤操作：

1. 从源代码克隆一份TopoNetX副本：

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

2. 如果你已经从源代码克隆了TopoNetX，请更新它：

git pull

3. 以可编辑模式安装TopoNetX（需要pip ≥ 21.3以支持PEP 660）：

pip install -e '.[all]'

4. 安装pre-commit钩子：

pre-commit install

🔍 参考文献

要了解更多关于拓扑域及其在深度学习中的应用：

• 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. 拓扑深度学习：超越图数据。

@misc{hajij2023topological,
      title={拓扑深度学习：超越图数据},
      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. 拓扑深度学习的架构：拓扑神经网络综述。

@misc{papillon2023architectures,
      title={拓扑深度学习的架构：拓扑神经网络综述},
      author={Mathilde Papillon and Sophia Sanborn and Mustafa Hajij and Nina Miolane},
      year={2023},
      eprint={2304.10031},
      archivePrefix={arXiv},
      primaryClass={cs.LG}
}

⭐ 致谢

TopoNetX的构建得益于多个开源软件包的帮助。 所有这些软件包都列在setup.py中。 其中一些包括：

• NetworkX
• HyperNetX
• gudhi
• trimesh

资金支持

<img align="right" width="200" src="https://yellow-cdn.veclightyear.com/ab5030c0/d23e79cc-bed5-4626-be82-8f58e1590fc2.png">

部分由欧盟资助（ERC, HIGH-HOPeS, 101039827）。然而，此处表达的观点和意见仅代表作者的观点，不一定反映欧盟或欧洲研究委员会执行机构的观点。欧盟和资助机构对这些观点不承担任何责任。

部分由美国国家科学基金会资助（DMS-2134231, DMS-2134241）。