Merge pull request #256 from geometric-intelligence/uv_env

Add uv installation script and support

Author: gbg141

.github/workflows/docs.yml

@@ -5,44 +5,51 @@ on:
     branches: [main, github-actions-test]
   pull_request:
     branches: [main]
+
 permissions:
   contents: write
 
 jobs:
   build:
-    runs-on: ${{matrix.os}}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        os: [ubuntu-latest]
-        python-version: [3.11.3]
-        torch-version: [2.0.1]
-        include:
-          - torch-version: 2.0.1
+        python-version: ["3.11"]
 
     steps:
-      - uses: actions/checkout@v3
-      - name: Build using Python ${{matrix.python-version}}
-        uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+
+      # 1. Setup uv
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
-          python-version: ${{matrix.python-version}}
-          cache: "pip"
-          cache-dependency-path: "pyproject.toml"
-      - name: Install dependencies [pip]
-        run: |
-          python -m pip install --upgrade pip
-          pip install pytest
-          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-          source env_setup.sh
-      - name: Install Pandoc [apt-get]
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      # 2. Run your centralized installation script
+      - name: Install dependencies (via script)
         run: |
-          sudo apt-get -y install pandoc
+          # This installs '.[all]' which includes doc dependencies
+          source uv_env_setup.sh
+
+      # 3. Install System Dependencies
+      - name: Install Pandoc
+        run: sudo apt-get -y install pandoc
+
+      # 4. Generate Docs
       - name: Generate API Documentation
         run: |
+          source .venv/bin/activate
           cd docs
           bash generate_api_docs.sh
+
       - name: Generate Docs [Sphinx]
         run: |
-          sphinx-build  -b html -D version=latest -D release=latest docs docs/_build
+          source .venv/bin/activate
+          sphinx-build -b html -D version=latest -D release=latest docs docs/_build
+
+      # 5. Deploy
       - name: Deploy Docs
         uses: JamesIves/github-pages-deploy-action@v4
         if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository == 'geometric-intelligence/TopoBench' }}

.github/workflows/lint.yml

@@ -6,11 +6,21 @@ on:
   pull_request:
     branches: [ main ]
 
+permissions:
+  contents: read
+
 jobs:
   ruff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: chartboost/ruff-action@v1
+      - uses: actions/checkout@v4
+
+      # We use the official action from Astral (creators of uv & ruff)
+      - name: Run Ruff
+        uses: astral-sh/ruff-action@v3
         with:
-          src: './topobench'
+          src: "./topobench"
+          # This ensures the ruff version matches what you have in pyproject.toml
+          version-file: "pyproject.toml"
+          # Optional: fails the build if the code changes (e.g. formatting)
+          changed-files: "true"

.github/workflows/test.yml

@@ -1,6 +1,3 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
 name: Testing
 
 on:
@@ -14,38 +11,38 @@ permissions:
 
 jobs:
   build:
-    runs-on: ${{matrix.os}}
+    runs-on: ubuntu-latest
     strategy:
       matrix:
-        os: [ubuntu-latest]
-        python-version: [3.11.3]
+        python-version: ["3.11"]
 
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python ${{matrix.python-version}}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{matrix.python-version}}
 
-      - uses: actions/cache@v4
+      # 1. Setup uv
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
         with:
-          path: ~/.cache/pip
-          key: ${{matrix.os}}-${{matrix.python-version}}-${{ hashFiles('pyproject.toml') }}
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
 
-      - name: Install dependencies
+      # 2. Run your centralized installation script
+      - name: Install dependencies (via script)
         run: |
-          python -m pip install --upgrade pip
-          pip install pytest
-          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-          source env_setup.sh
+          # This script handles the .venv creation and PyTorch/CUDA logic
+          source uv_env_setup.sh
 
+      # 3. Run Tests
       - name: Test with pytest
         run: |
+          # We must activate the venv created by your script
+          source .venv/bin/activate
           pytest --cov --cov-report=xml:coverage.xml test/
 
       - name: Upload coverage reports to Codecov
         uses: codecov/codecov-action@v4.0.1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           file: coverage.xml
-          fail_ci_if_error: false
+          fail_ci_if_error: false

.gitignore

@@ -194,3 +194,4 @@ wandb/
 
 # test temporary
 .test_tmp/
+uv.lock

README.md

@@ -52,44 +52,58 @@ The main pipeline trains and evaluates a wide range of state-of-the-art TNNs and
 
 ## :jigsaw: Get Started
 
-### Create Environment
+### 🚀 Quick Install (Recommended)
 
-First, ensure `conda` is installed:  
-```bash
-conda --version
-```
-If not, we recommend intalling Miniconda [following the official command line instructions](https://www.anaconda.com/docs/getting-started/miniconda/install).
+TopoBench now uses [**uv**](https://docs.astral.sh/uv/), an extremely fast Python package manager and resolver. This allows for nearly instantaneous environment setup and reproducible builds.
 
-Then, clone and navigate to the `TopoBench` repository  
-```bash
-git clone git@github.com:geometric-intelligence/topobench.git
-cd TopoBench
-```
+1.  [**Install uv**](https://docs.astral.sh/uv/getting-started/installation/#standalone-installer)
 
-Next, set up and activate a conda environment `tb` with Python 3.11.3:
-```bash
-conda create -n tb python=3.11.3
-conda activate tb
-```
+2.  **Clone and Navigate**:
+    ```bash
+    git clone git@github.com:geometric-intelligence/topobench.git
+    cd TopoBench
+    ```
 
-If working with GPUs, check the CUDA version of your machine:
-```bash
-which nvcc && nvcc --version
-```
-and ensure that it matches the CUDA version specified in the `env_setup.sh` file (`CUDA=cpu` by default for a broader compatibility). If it does not match, update `env_setup.sh` accordingly by changing both the `CUDA` and `TORCH` environment variables to compatible values as specified on [this website](https://github.com/pyg-team/pyg-lib).
+3.  **Initialize Environment**:
+    Use our centralized setup script to handle Python 3.11 virtualization and specialized hardware (CUDA) mapping.
+    ```bash
+    # Usage: source uv_env_setup.sh [cpu|cu118|cu121]
+    source uv_env_setup.sh cpu
+    ```
+    *This script performs the following:*
+    * Creates a `.venv` using Python 3.11.
+    * Dynamically configures `pyproject.toml` to point to the correct **PyTorch** and **PyG** (PyTorch Geometric) wheels for your platform.
+    * Generates a precise `uv.lock` file and syncs all dependencies.
+
+---
+
+### 🛠️ Manual Environment Setup
+
+If you prefer to manage the environment manually or are integrating into an existing workflow:
 
-Next, set up the environment with the following command.
 ```bash
-source env_setup.sh
+# Create a virtual environment with strict versioning
+uv venv --python 3.11
+source .venv/bin/activate
+
+# Sync dependencies including all extras (dev, test, and doc)
+uv sync --all-extras
 ```
-This command installs the `TopoBench` library and its dependencies. 
 
-### Run Training Pipeline
+🚄 Run Training Pipeline
+Once the environment is active, you can launch the TopoBench pipeline:
+```bash
+# Using the activated virtual environment
+python -m topobench 
 
-Once the setup is completed, train and evaluate a neural network by running the following command:
+# Or execute directly via uv without manual activation
+uv run python -m topobench
+```
 
+✅ Verify Installation
+You can verify that the correct versions of Torch and CUDA are detected by running:
 ```bash
-python -m topobench 
+python -c "import torch; print(f'Torch: {torch.__version__} | CUDA: {torch.version.cuda}')"
 ```
 
 ---
@@ -390,14 +404,15 @@ Specially useful in pre-processing steps, these are the general data manipulatio
 To learn more about `TopoBench`, we invite you to read the paper:
 
 ```
-@article{telyatnikov2024topobench,
-      title={TopoBench: A Framework for Benchmarking Topological Deep Learning}, 
-      author={Lev Telyatnikov and Guillermo Bernardez and Marco Montagna and Pavlo Vasylenko and Ghada Zamzmi and Mustafa Hajij and Michael T Schaub and Nina Miolane and Simone Scardapane and Theodore Papamarkou},
-      year={2024},
-      eprint={2406.06642},
-      archivePrefix={arXiv},
-      primaryClass={cs.LG},
-      url={https://arxiv.org/abs/2406.06642}, 
+@article{
+telyatnikov2025topobench,
+title={TopoBench: A Framework for Benchmarking Topological Deep Learning},
+author={Lev Telyatnikov and Guillermo Bernardez and Marco Montagna and Mustafa Hajij and Martin Carrasco and Pavlo Vasylenko and Mathilde Papillon and Ghada Zamzmi and Michael T Schaub and Jonas Verhellen and Pavel Snopov and Bertran Miquel-Oliver and Manel Gil-Sorribes and Alexis Molina and VICTOR GUALLAR and Theodore Long and Julian Suk and Patryk Rygiel and Alexander V Nikitin and Giordan Escalona and Michael Banf and Dominik Filipiak and Liliya Imasheva and Max Schattauer and Alvaro L. Martinez and Halley Fritze and Marissa Masden and Valentina S{\'a}nchez and Manuel Lecha and Andrea Cavallo and Claudio Battiloro and Matthew Piekenbrock and Mauricio Tec and George Dasoulas and Nina Miolane and Simone Scardapane and Theodore Papamarkou},
+journal={Journal of Data-centric Machine Learning Research},
+issn={XXXX-XXXX},
+year={2025},
+url={https://openreview.net/forum?id=07sTzyEVtY},
+note={}
 }
 ```
 If you find `TopoBench` useful, we would appreciate if you cite us!