Support Python 3.13 / Torch 2.12 and rework the tested install path (#345)

* Normalize tested install dependencies

* Clarify deprecated torch-scatter helper

* Clarify standalone and library install paths

* Align GPU workflow and cu130 wheel index

Author: QG-phy

.github/workflows/gpu_compat.yml

@@ -28,7 +28,7 @@ jobs:
     timeout-minutes: 180
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
@@ -41,7 +41,7 @@ jobs:
 
       - name: Install DeePTB GPU stack
         run: |
-          bash install.sh "${{ inputs.backend }}" --extra pythtb --test
+          bash install.sh "${{ inputs.backend }}" --extra pythtb
 
       - name: CUDA and torch-scatter smoke
         run: |

.gitignore

@@ -153,6 +153,7 @@ celerybeat.pid
 # Environments
 .env
 .venv
+.compat-envs/
 env/
 venv/
 ENV/
@@ -184,6 +185,9 @@ dptb/_version.py
 poetry.lock
 poetry.toml
 
+# Compatibility test outputs
+tools/compat/results*/
+
 # JetBrains
 .idea/
 CLAUDE.md

Dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:20.04
+FROM ubuntu:24.04
 SHELL ["/bin/bash", "-c"]
 
 ARG MINIFORGE_NAME=Miniforge3

Dockerfile.main

@@ -1,4 +1,4 @@
-FROM ubuntu:20.04
+FROM ubuntu:24.04
 
 SHELL ["/bin/bash", "-c"]
 

README.md

@@ -58,7 +58,7 @@ Installing **DeePTB** is straightforward with UV, a fast Python package manager.
 - **Requirements**
   - Git
   - Python 3.10 to 3.13
-  - UV, the recommended installer frontend
+  - UV, used by `install.sh` as the fast installer frontend
   - For GPU installs: an NVIDIA driver compatible with the selected CUDA runtime
 
 - **From Source** (Recommended)
@@ -107,9 +107,34 @@ Installing **DeePTB** is straightforward with UV, a fast Python package manager.
      - Automatically create a virtual environment (`.venv`)
      - Install a tested PyTorch / PyG / `torch-scatter` binary-wheel combination
      - Refuse unsupported Python or CUDA/backend combinations instead of falling back to source builds
-     - Install all other dependencies
+     - Install all runtime and test dependencies
 
-  4. **Install optional dependencies** (if needed):
+  4. **Activate the standalone environment**:
+
+     `install.sh` installs DeePTB into `.venv` under the current DeePTB
+     repository. Activate it before running `dptb`:
+
+     ```bash
+     source .venv/bin/activate  # On Unix/macOS
+     .venv\Scripts\activate     # On Windows
+     dptb --help
+     ```
+
+  5. **Validate the installation**:
+     DeePTB is under active development, so new installations should run the
+     test suite once before production use.
+
+     ```bash
+     python -m pytest ./dptb/tests/
+     ```
+
+     For a faster local check while iterating:
+
+     ```bash
+     python -m pytest ./dptb/tests/ -m "not slow"
+     ```
+
+  6. **Install optional dependencies** (if needed):
      ```bash
      # For 3D Fermi surface plotting
      ./install.sh auto --extra 3Dfermi
@@ -121,13 +146,6 @@ Installing **DeePTB** is straightforward with UV, a fast Python package manager.
      ./install.sh auto --extra pybinding
      ```
 
-  5. **Run DeePTB**:
-     ```bash
-     source .venv/bin/activate  # On Unix/macOS
-     .venv\Scripts\activate     # On Windows
-     dptb --help
-     ```
-
 - **Developer Install**
 
   `pyproject.toml` declares the broader source-compatible range
@@ -138,39 +156,61 @@ Installing **DeePTB** is straightforward with UV, a fast Python package manager.
   uv sync
   ```
 
-  For new machines, prefer `install.sh` because it selects a tested
-  `torch-scatter` binary wheel for the requested CPU/GPU backend.
+  This path is for developers who intentionally manage their own environment.
+  For a tested standalone DeePTB environment, prefer `install.sh`.
 
-- **Easy Installation** (PyPI)
+- **Library Installation** (Existing Environment)
 
   > [!WARNING]
-  > PyPI installation requires a compatible PyTorch and `torch-scatter` binary
-  > wheel to be installed first. The source install path above is easier for new
-  > machines.
+  > This path is for downstream projects or existing environments that import
+  > DeePTB as a library. The environment must provide a compatible PyTorch and
+  > `torch-scatter` binary wheel.
 
-  **For CPU**:
-  ```bash
-  # 1. Install torch_scatter matching the tested CPU Torch version
-  pip install torch-scatter -f https://data.pyg.org/whl/torch-2.12.1+cpu.html
+  DeePTB keeps a broad Torch compatibility range so downstream projects can
+  choose their own CPU/GPU backend. In that case, install PyTorch first, then
+  install a `torch-scatter` binary wheel matching the current Torch version and
+  backend. If you are working from a DeePTB source checkout, the helper can
+  inspect the current environment and print the matching PyG wheel command:
 
-  # 2. Install DeePTB
-  pip install dptb
+  ```bash
+  python - <<'PY'
+  import torch
+  print("torch:", torch.__version__)
+  print("cuda runtime:", torch.version.cuda)
+  print("cuda available:", torch.cuda.is_available())
+  PY
+
+  python docs/auto_install_torch_scatter.py --dry-run
+  python docs/auto_install_torch_scatter.py
   ```
 
-  **For GPU** (example with CUDA 12.8 / RTX 50):
+  Then install DeePTB from the current source checkout:
+
   ```bash
-  # 1. Install torch with CUDA support.
-  pip install torch==2.10.0 --index-url https://download.pytorch.org/whl/cu128
+  pip install .
+  ```
 
-  # 2. Install torch_scatter matching the Torch/CUDA pair.
-  pip install torch-scatter -f https://data.pyg.org/whl/torch-2.10.0+cu128.html
+  Use `pip install -e .` instead if you want an editable developer install.
+  Published package installs, such as `pip install dptb`, were not part of this
+  compatibility test pass; prefer a source checkout until that path is tested.
 
-  # 3. Install DeePTB
-  pip install dptb
-  ```
+  For standalone DeePTB use on a new machine, use the **From Source** installer
+  above instead; it creates `.venv` and selects a tested Torch / PyG /
+  `torch-scatter` combination.
 
-  > [!TIP]
-  > For easier installation with automatic GPU/CPU detection, use the **From Source** method above instead.
+  Example manual `torch-scatter` commands:
+
+  ```bash
+  # CPU, torch 2.12.1
+  pip install --only-binary torch-scatter \
+    torch-scatter==2.1.2 \
+    -f https://data.pyg.org/whl/torch-2.12.1+cpu.html
+
+  # CUDA 12.8 / torch 2.10.0
+  pip install --only-binary torch-scatter \
+    torch-scatter==2.1.2+pt210cu128 \
+    -f https://data.pyg.org/whl/torch-2.10.0+cu128.html
+  ```
 
 - **Julia Backend** (Optional - for High-Performance Pardiso Solver)
 
@@ -215,7 +255,7 @@ Installing **DeePTB** is straightforward with UV, a fast Python package manager.
 
 To ensure the code is correctly installed, please run the unit tests first:
 ```bash
-uv run pytest ./dptb/tests/
+python -m pytest ./dptb/tests/
 ```
 Be careful if not all tests pass!
 

docs/auto_install_torch_scatter.py

@@ -1,33 +1,118 @@
-# NOTE: This script is no longer needed when using UV package manager.
-# UV will automatically install torch_scatter from the configured index in pyproject.toml.
-# This script is kept for reference and for users not using UV.
+"""Install torch-scatter for the currently installed PyTorch.
 
+This helper is for library/downstream installs where the environment already
+owns its PyTorch stack. For standalone DeePTB installs, prefer ``install.sh``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
 import subprocess
+import sys
+from importlib import metadata
+
+
+SCATTER_VERSION = "2.1.2"
+
+
+def normalize_torch_version(version: str) -> tuple[str, str]:
+    match = re.match(r"^(\d+\.\d+\.\d+)(?:\+([A-Za-z0-9_]+))?", version)
+    if not match:
+        raise SystemExit(f"ERROR: cannot parse torch version: {version}")
+
+    base_version = match.group(1)
+    backend = match.group(2) or "cpu"
+    if backend.startswith("cu"):
+        return base_version, backend
+    return base_version, "cpu"
+
+
+def scatter_requirement(torch_base: str, backend: str) -> str:
+    if backend == "cpu":
+        return f"torch-scatter=={SCATTER_VERSION}"
+
+    major, minor, _patch = torch_base.split(".")
+    return f"torch-scatter=={SCATTER_VERSION}+pt{major}{minor}{backend}"
 
-try:
-    import torch
-    print("The torch module has been successfully imported!")
 
-    torch_version = torch.__version__
-    print(f"Current torch version: {torch_version}")
+def installed_scatter_version() -> str | None:
+    try:
+        return metadata.version("torch-scatter")
+    except metadata.PackageNotFoundError:
+        return None
+
 
-    if torch.cuda.is_available():
-        cuda_version = torch.version.cuda
-    else:
-        cuda_version = "cpu"
-    print(f"Versions of CUDA used by PyTorch: {cuda_version}")
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Install a torch-scatter binary wheel matching the current torch "
+            "version and CPU/CUDA backend."
+        )
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the pip command without installing anything.",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Reinstall torch-scatter even if it is already importable.",
+    )
+    args = parser.parse_args()
 
     try:
-        import torch_scatter
-        print("You have already installed torch-scatter!")
-
-    except ImportError:
-        url = f"https://data.pyg.org/whl/torch-{torch_version}.html"
-        print(f"torch-scatter will be installed from {url}...")
-        subprocess.run(["pip", "install", "torch-scatter==2.1.2", "-f", url], check=True)
-        print("Installation complete, please re-run the program.")
-
-except ImportError:
-    print("The torch module is not found, please install PyTorch first.")
-    print("You can install PyTorch with the following command (version range: 2.0.0-2.5.1) :")
-    print("pip install \"torch>=2.0.0,<=2.5.1\"")
+        import torch
+    except ImportError as exc:
+        raise SystemExit(
+            "ERROR: torch is not installed in this environment. Install the "
+            "PyTorch build required by your project first, then rerun this "
+            "helper."
+        ) from exc
+
+    torch_base, backend = normalize_torch_version(torch.__version__)
+    find_links = f"https://data.pyg.org/whl/torch-{torch_base}+{backend}.html"
+    requirement = scatter_requirement(torch_base, backend)
+
+    current_scatter = installed_scatter_version()
+    print("Detected environment:")
+    print(f"  Python:          {sys.version.split()[0]}")
+    print(f"  torch:           {torch.__version__}")
+    print(f"  CUDA runtime:    {torch.version.cuda}")
+    print(f"  CUDA available:  {torch.cuda.is_available()}")
+    print(f"  PyG wheel index: {find_links}")
+    print(f"  torch-scatter:   {requirement}")
+
+    if current_scatter and not args.force:
+        required_version = requirement.split("==", 1)[1].lower()
+        if current_scatter.lower() == required_version:
+            print(f"torch-scatter is already installed: {current_scatter}")
+            return
+        print(f"torch-scatter is already installed: {current_scatter}")
+        print(f"The detected torch backend expects: {required_version}")
+        print("Use --force to reinstall it for the detected torch backend.")
+        raise SystemExit(1)
+
+    command = [
+        sys.executable,
+        "-m",
+        "pip",
+        "install",
+        "--only-binary",
+        "torch-scatter",
+        requirement,
+        "-f",
+        find_links,
+    ]
+
+    print("Command:")
+    print("  " + " ".join(command))
+    if args.dry_run:
+        return
+
+    subprocess.run(command, check=True)
+
+
+if __name__ == "__main__":
+    main()