ninamiolane / TopoModelX

Topological Deep Learning

🌐 TopoModelX (TMX) 🍩

Topological Deep Learning

TopoModelX (TMX) is a Python module for topological deep learning, which simple and efficient solutions for science and engineering.

TMX's development follows the topological deep learning (TDL) blue print laid out in:

• Hajij et al. 2023. Topological Deep Learning: Going Beyond Graph Data.

TMX can reproduce and extend the topological neural networks (TNNs) surveyed in:

• Papillon et al. 2023. Architectures of Topological Deep Learning: A Survey on Topological Neural Networks.

See our graphical literature review with equations available at https://github.com/awesome-tnns/awesome-tnns.

Note: TMX is still under development. Use at your own risk.

🦾 Contributing to TMX

To develop tmx on your machine, here are some tips.

First, we recommend using Python 3.10, which the python version used to run the unit-tests.

Then:

1. Clone a copy of tmx from source:

   git clone [e-mail]:pyt-team/TopoModelX.git
   cd TopoModelX

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

   git pull

3. Install tmx in editable mode:

   pip install -e ".[all]"

   This mode will symlink the Python files from the current local source tree into the Python install. Hence, if you modify a Python file, you do not need to reinstall tmx again and again.

4. Install torch, torch-scatter, torch-sparse with or without CUDA depending on your needs.

   To install the binaries for PyTorch 1.12.0, simply run:

   pip install torch==1.12.0 --extra-index-url https://download.pytorch.org/whl/${CUDA}
   pip install torch-scatter torch-sparse torch_geometric -f https://data.pyg.org/whl/torch-1.12.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

   pytest

   In case an error occurs, please first check if all sub-packages (torch-scatter, torch-sparse, torch-cluster and torch-spline-conv) are on its latest reported version.

6. Install pre-commit hooks:

   pip install pre-commit
   pre-commit install

🔍 References

To learn more about the topological deep learning blueprint:

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