| Name | TopoModelX JSON |
| Version |
0.0.1
JSON |
| download |
| home_page | None |
| Summary | Topological Deep Learning |
| upload_time | 2024-10-20 22:24:10 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h2 align="center">
<img src="https://raw.githubusercontent.com/pyt-team/TopoModelX/main/resources/logo.png" height="250">
</h2>
<h3 align="center">
Building Topological Neural Networks for Topological Deep Learning
</h3>
<p align="center">
<a href="#-contributing-to-tmx">Contributing to TMX</a> •
<a href="#-references">References</a>
</p>
<div align="center">
[](https://github.com/pyt-team/torch_topo/actions/workflows/test_codebase.yml)
[](https://github.com/pyt-team/torch_topo/actions/workflows/test_tutorials.yml)
[](https://github.com/pyt-team/torch_topo/actions/workflows/lint.yml)
[](https://app.codecov.io/gh/pyt-team/TopoModelX)
[](https://pyt-team.github.io/topomodelx/index.html)
[](https://www.python.org/)
[](https://github.com/pyt-team/TopoNetX/blob/main/LICENSE)
[](https://join.slack.com/t/pyt-teamworkspace/shared_invite/zt-2k63sv99s-jbFMLtwzUCc8nt3sIRWjEw)
[](https://doi.org/10.5281/zenodo.7958513)
</div>
`TopoModelX` (TMX) is a Python module for topological deep learning. It offers simple and efficient tools to implement topological neural networks for science and engineering.
_**Note:** TMX is still under development._
## Quick Tour for New Users
In this quick tour, we highlight the ease of creating and training a TNN model with only a few lines of code.
#Train your own TNN model
Below is a minimal example of using TopoModelX to load a simplicial complex dataset, define a simplicial attention network (SAN), and perform a forward pass:
```bash
import numpy as np
import torch
from topomodelx.datasets.graph import karate_club
from topomodelx.nn.simplicial.san import SAN
from topomodelx.utils.sparse import from_sparse
# Step 1: Load the Karate Club dataset
dataset = karate_club(complex_type="simplicial")
# Step 2: Prepare Laplacians and node/edge features
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())))
x_1 = torch.tensor(np.stack(list(dataset.get_simplex_attributes("edge_feat").values())))
x = x_1 + torch.sparse.mm(incidence_0_1.T, x_0)
# Step 3: Define the network
class Network(torch.nn.Module):
def __init__(self, in_channels, hidden_channels, out_channels):
super().__init__()
self.base_model = 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):
x = self.base_model(x, laplacian_up, laplacian_down)
return torch.sigmoid(self.linear(x))
# Step 4: Initialize the network and perform a forward pass
model = Network(in_channels=x.shape[-1], hidden_channels=16, out_channels=2)
y_hat_edge = model(x, laplacian_up=laplacian_up, laplacian_down=laplacian_down)
```
## 🦾 Contributing to TMX
To develop tmx on your machine, here are some tips.
First, we recommend using Python 3.11.3, which is the python version used to run the unit-tests.
For example, create a conda environment:
```bash
conda create -n tmx python=3.11.3
conda activate tmx
```
Then:
1. Clone a copy of tmx from source:
```bash
git clone git@github.com:pyt-team/TopoModelX.git
cd TopoModelX
```
2. Install tmx in editable mode:
```bash
pip install -e '.[all]'
```
**Notes:**
- Requires pip >= 21.3. Refer: [PEP 660](https://peps.python.org/pep-0660/).
- On Windows, use `pip install -e .[all]` instead (without quotes around `[all]`).
4. Install torch, torch-scatter, torch-sparse with or without CUDA depending on your needs.
```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
```
where `${CUDA}` should be replaced by either `cpu`, `cu102`, `cu113`, or `cu115` depending on your PyTorch installation (`torch.version.cuda`).
5. Ensure that you have a working tmx installation by running the entire test suite with
```bash
pytest
```
In case an error occurs, please first check if all sub-packages ([`torch-scatter`](https://github.com/rusty1s/pytorch_scatter), [`torch-sparse`](https://github.com/rusty1s/pytorch_sparse), [`torch-cluster`](https://github.com/rusty1s/pytorch_cluster) and [`torch-spline-conv`](https://github.com/rusty1s/pytorch_spline_conv)) are on its latest reported version.
6. Install pre-commit hooks:
```bash
pre-commit install
```
## 🔍 References ##
TMX is a part of TopoX, a suite of Python packages for machine learning on topological domains. If you find TMX useful please consider citing our software paper:
- Hajij et al. 2023. TopoX: a suite of Python packages for machine learning on topological domains
To learn more about the blueprint topological deep learning that topomodelx follows :
- 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/)
TMX topological neural networks are surveyed in:
- Papillon et al. 2023. Architectures of Topological Deep Learning: A Survey on Topological Neural Networks.
```
@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}
}
@article{hajij2024topox,
title={TopoX: a suite of Python packages for machine learning on topological domains},
author={PYT-Team},
journal={arXiv preprint arXiv:2402.02441},
year={2024}
}
@article{papillon2023architectures,
title={Architectures of Topological Deep Learning: A Survey of Message-Passing Topological Neural Networks},
author={Papillon, Mathilde and Sanborn, Sophia and Hajij, Mustafa and Miolane, Nina},
journal={arXiv preprint arXiv:2304.10031},
year={2023}
}
```
## Funding
<img align="right" width="200" src="https://raw.githubusercontent.com/pyt-team/TopoNetX/main/resources/erc_logo.png">
Partially 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.
Partially funded by the National Science Foundation (DMS-2134231, DMS-2134241).
Raw data
{
"_id": null,
"home_page": null,
"name": "TopoModelX",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "PyT-Team Authors <mustafahajij@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/12/4c/01f0d9a21f982d049915e4f16fe8d0b553e9ab7c1a112c9a3537d27a4ce7/topomodelx-0.0.1.tar.gz",
"platform": null,
"description": "<h2 align=\"center\">\r\n <img src=\"https://raw.githubusercontent.com/pyt-team/TopoModelX/main/resources/logo.png\" height=\"250\">\r\n</h2>\r\n\r\n<h3 align=\"center\">\r\n Building Topological Neural Networks for Topological Deep Learning\r\n</h3>\r\n\r\n<p align=\"center\">\r\n <a href=\"#-contributing-to-tmx\">Contributing to TMX</a> \u2022\r\n <a href=\"#-references\">References</a>\r\n</p>\r\n\r\n<div align=\"center\">\r\n\r\n[](https://github.com/pyt-team/torch_topo/actions/workflows/test_codebase.yml)\r\n[](https://github.com/pyt-team/torch_topo/actions/workflows/test_tutorials.yml)\r\n[](https://github.com/pyt-team/torch_topo/actions/workflows/lint.yml)\r\n[](https://app.codecov.io/gh/pyt-team/TopoModelX)\r\n[](https://pyt-team.github.io/topomodelx/index.html)\r\n[](https://www.python.org/)\r\n[](https://github.com/pyt-team/TopoNetX/blob/main/LICENSE)\r\n\r\n[](https://join.slack.com/t/pyt-teamworkspace/shared_invite/zt-2k63sv99s-jbFMLtwzUCc8nt3sIRWjEw)\r\n[](https://doi.org/10.5281/zenodo.7958513)\r\n\r\n</div>\r\n\r\n\r\n\r\n\r\n`TopoModelX` (TMX) is a Python module for topological deep learning. It offers simple and efficient tools to implement topological neural networks for science and engineering.\r\n\r\n_**Note:** TMX is still under development._\r\n\r\n## Quick Tour for New Users\r\n\r\nIn this quick tour, we highlight the ease of creating and training a TNN model with only a few lines of code.\r\n\r\n#Train your own TNN model\r\n\r\nBelow is a minimal example of using TopoModelX to load a simplicial complex dataset, define a simplicial attention network (SAN), and perform a forward pass:\r\n\r\n\r\n```bash\r\nimport numpy as np\r\nimport torch\r\nfrom topomodelx.datasets.graph import karate_club\r\nfrom topomodelx.nn.simplicial.san import SAN\r\nfrom topomodelx.utils.sparse import from_sparse\r\n\r\n# Step 1: Load the Karate Club dataset\r\ndataset = karate_club(complex_type=\"simplicial\")\r\n\r\n# Step 2: Prepare Laplacians and node/edge features\r\nlaplacian_down = from_sparse(dataset.down_laplacian_matrix(rank=1))\r\nlaplacian_up = from_sparse(dataset.up_laplacian_matrix(rank=1))\r\nincidence_0_1 = from_sparse(dataset.incidence_matrix(rank=1))\r\n\r\nx_0 = torch.tensor(np.stack(list(dataset.get_simplex_attributes(\"node_feat\").values())))\r\nx_1 = torch.tensor(np.stack(list(dataset.get_simplex_attributes(\"edge_feat\").values())))\r\nx = x_1 + torch.sparse.mm(incidence_0_1.T, x_0)\r\n\r\n# Step 3: Define the network\r\nclass Network(torch.nn.Module):\r\n def __init__(self, in_channels, hidden_channels, out_channels):\r\n super().__init__()\r\n self.base_model = SAN(in_channels, hidden_channels, n_layers=2)\r\n self.linear = torch.nn.Linear(hidden_channels, out_channels)\r\n\r\n def forward(self, x, laplacian_up, laplacian_down):\r\n x = self.base_model(x, laplacian_up, laplacian_down)\r\n return torch.sigmoid(self.linear(x))\r\n\r\n# Step 4: Initialize the network and perform a forward pass\r\nmodel = Network(in_channels=x.shape[-1], hidden_channels=16, out_channels=2)\r\ny_hat_edge = model(x, laplacian_up=laplacian_up, laplacian_down=laplacian_down)\r\n ```\r\n\r\n## \ud83e\uddbe Contributing to TMX\r\n\r\nTo develop tmx on your machine, here are some tips.\r\n\r\nFirst, we recommend using Python 3.11.3, which is the python version used to run the unit-tests.\r\n\r\nFor example, create a conda environment:\r\n ```bash\r\n conda create -n tmx python=3.11.3\r\n conda activate tmx\r\n ```\r\n\r\nThen:\r\n\r\n1. Clone a copy of tmx from source:\r\n\r\n ```bash\r\n git clone git@github.com:pyt-team/TopoModelX.git\r\n cd TopoModelX\r\n ```\r\n\r\n2. Install tmx in editable mode:\r\n\r\n ```bash\r\n pip install -e '.[all]'\r\n ```\r\n **Notes:**\r\n - Requires pip >= 21.3. Refer: [PEP 660](https://peps.python.org/pep-0660/).\r\n - On Windows, use `pip install -e .[all]` instead (without quotes around `[all]`).\r\n\r\n4. Install torch, torch-scatter, torch-sparse with or without CUDA depending on your needs.\r\n\r\n ```bash\r\n pip install torch==2.0.1 --extra-index-url https://download.pytorch.org/whl/${CUDA}\r\n pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.0.1+${CUDA}.html\r\n pip install torch-cluster -f https://data.pyg.org/whl/torch-2.0.0+${CUDA}.html\r\n ```\r\n\r\n where `${CUDA}` should be replaced by either `cpu`, `cu102`, `cu113`, or `cu115` depending on your PyTorch installation (`torch.version.cuda`).\r\n\r\n5. Ensure that you have a working tmx installation by running the entire test suite with\r\n\r\n ```bash\r\n pytest\r\n ```\r\n\r\n In case an error occurs, please first check if all sub-packages ([`torch-scatter`](https://github.com/rusty1s/pytorch_scatter), [`torch-sparse`](https://github.com/rusty1s/pytorch_sparse), [`torch-cluster`](https://github.com/rusty1s/pytorch_cluster) and [`torch-spline-conv`](https://github.com/rusty1s/pytorch_spline_conv)) are on its latest reported version.\r\n\r\n6. Install pre-commit hooks:\r\n\r\n ```bash\r\n pre-commit install\r\n ```\r\n\r\n## \ud83d\udd0d References ##\r\n\r\nTMX is a part of TopoX, a suite of Python packages for machine learning on topological domains. If you find TMX useful please consider citing our software paper:\r\n\r\n- Hajij et al. 2023. TopoX: a suite of Python packages for machine learning on topological domains\r\n\r\nTo learn more about the blueprint topological deep learning that topomodelx follows :\r\n\r\n- Mustafa Hajij, Ghada Zamzmi, Theodore Papamarkou, Nina Miolane, Aldo Guzm\u00e1n-S\u00e1enz, Karthikeyan Natesan Ramamurthy, Tolga Birdal, Tamal K. Dey, Soham Mukherjee, Shreyas N. Samaga, Neal Livesay, Robin Walters, Paul Rosen, Michael T. Schaub. \r\n [Topological Deep Learning: Going Beyond Graph Data](https://arxiv.org/abs/2206.00606) (arXiv) \u2022 [Topological Deep Learning: A Book](https://tdlbook.org/)\r\n\r\nTMX topological neural networks are surveyed in:\r\n\r\n- Papillon et al. 2023. Architectures of Topological Deep Learning: A Survey on Topological Neural Networks.\r\n\r\n```\r\n@misc{hajij2023topological,\r\n title={Topological Deep Learning: Going Beyond Graph Data},\r\n author={Mustafa Hajij and Ghada Zamzmi and Theodore Papamarkou and Nina Miolane and Aldo Guzm\u00e1n-S\u00e1enz 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},\r\n year={2023},\r\n eprint={2206.00606},\r\n archivePrefix={arXiv},\r\n primaryClass={cs.LG}\r\n}\r\n\r\n@article{hajij2024topox,\r\n title={TopoX: a suite of Python packages for machine learning on topological domains},\r\n author={PYT-Team},\r\n journal={arXiv preprint arXiv:2402.02441},\r\n year={2024}\r\n}\r\n\r\n@article{papillon2023architectures,\r\n title={Architectures of Topological Deep Learning: A Survey of Message-Passing Topological Neural Networks},\r\n author={Papillon, Mathilde and Sanborn, Sophia and Hajij, Mustafa and Miolane, Nina},\r\n journal={arXiv preprint arXiv:2304.10031},\r\n year={2023}\r\n}\r\n\r\n```\r\n## Funding\r\n\r\n<img align=\"right\" width=\"200\" src=\"https://raw.githubusercontent.com/pyt-team/TopoNetX/main/resources/erc_logo.png\">\r\n\r\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.\r\n\r\nPartially funded by the National Science Foundation (DMS-2134231, DMS-2134241).\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Topological Deep Learning",
"version": "0.0.1",
"project_urls": {
"documentation": "https://pyt-team.github.io/TopoModelX",
"homepage": "https://github.com/pyt-team/TopoModelX",
"issues": "https://github.com/pyt-team/TopoModelX/issues",
"repository": "https://github.com/pyt-team/TopoModelX"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "506fedd56d8e4e726b311df85cbe8f3ad79f4706e9f1328e52922a4a868f8aa0",
"md5": "579ccca9c96a584691aae616c8938584",
"sha256": "6b5ebf3109715003ccfb73d1fb9aa9cdb3ac19ce968ecfafaade6a8220c711d4"
},
"downloads": -1,
"filename": "TopoModelX-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "579ccca9c96a584691aae616c8938584",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 107887,
"upload_time": "2024-10-20T22:24:08",
"upload_time_iso_8601": "2024-10-20T22:24:08.414100Z",
"url": "https://files.pythonhosted.org/packages/50/6f/edd56d8e4e726b311df85cbe8f3ad79f4706e9f1328e52922a4a868f8aa0/TopoModelX-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "124c01f0d9a21f982d049915e4f16fe8d0b553e9ab7c1a112c9a3537d27a4ce7",
"md5": "5838c2b5083fd48138a21c9f6bf7ff2a",
"sha256": "d804cb6201dbfa3836061472f1ef48a6758410a6d424dc700546b47271f10efd"
},
"downloads": -1,
"filename": "topomodelx-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "5838c2b5083fd48138a21c9f6bf7ff2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 66905,
"upload_time": "2024-10-20T22:24:10",
"upload_time_iso_8601": "2024-10-20T22:24:10.568972Z",
"url": "https://files.pythonhosted.org/packages/12/4c/01f0d9a21f982d049915e4f16fe8d0b553e9ab7c1a112c9a3537d27a4ce7/topomodelx-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-20 22:24:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyt-team",
"github_project": "TopoModelX",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "topomodelx"
}
