Promote Cortado as PerTurbo v2 successor

Author: logan-blaine

.dockerignore

@@ -0,0 +1,13 @@
+.git
+.venv
+.pytest_cache
+.ruff_cache
+__pycache__
+.test_outputs
+dist
+build
+docs
+tests
+*.h5ad
+*.h5mu
+*.ipynb

.github/workflows/build.yaml

@@ -1,29 +1,22 @@
-name: Check Build
+name: Check build
 
 on:
   push:
     branches: [main]
   pull_request:
     branches: [main]
 
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
 jobs:
   package:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python 3.10
-        uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
-          cache: "pip"
-          cache-dependency-path: "**/pyproject.toml"
-      - name: Install build dependencies
-        run: python -m pip install --upgrade pip wheel twine build
-      - name: Build package
-        run: python -m build
-      - name: Check package
-        run: twine check --strict dist/*.whl
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv run --with twine twine check --strict dist/*
+      - run: uv venv /tmp/perturbo-wheel
+      - run: uv pip install --python /tmp/perturbo-wheel/bin/python dist/*.whl
+      - run: /tmp/perturbo-wheel/bin/perturbo --help

.github/workflows/docker.yaml

@@ -2,23 +2,22 @@ name: Build & Push CUDA Image (GHCR)
 
 on:
   push:
-    # branches: [ main ]
-    tags: [ 'v*' ]      # build on version tags, e.g. v1.2.3
-  workflow_dispatch: {}  # allow manual runs
+    # Version tags are the intentional release boundary for container images.
+    tags: ["v*"]
+  workflow_dispatch: {}
 
 permissions:
   contents: read
-  packages: write   # REQUIRED for ghcr.io
+  packages: write
 
 jobs:
   build:
     runs-on: ubuntu-latest
-
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Set up QEMU (for cross-arch emulation)
+      - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
 
       - name: Set up Docker Buildx
@@ -31,22 +30,21 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Extract metadata (tags, labels)
+      - name: Extract metadata
         id: meta
         uses: docker/metadata-action@v5
         with:
           images: ghcr.io/${{ github.repository }}
           tags: |
-            type=ref,event=branch
             type=ref,event=tag
             type=sha
 
-      - name: Build & Push
+      - name: Build and push JAX CUDA image
         uses: docker/build-push-action@v6
         with:
           context: .
-          file: ./Dockerfile            # change if your Dockerfile path differs
-          platforms: linux/amd64        # most HPC nodes are amd64; add linux/arm64 if needed
+          file: ./Dockerfile
+          platforms: linux/amd64
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}

.github/workflows/release.yaml

@@ -4,26 +4,19 @@ on:
   release:
     types: [published]
 
-# Use "trusted publishing", see https://docs.pypi.org/trusted-publishers/
 jobs:
   release:
-    name: Upload release to PyPI
     runs-on: ubuntu-latest
     environment:
       name: pypi
       url: https://pypi.org/p/perturbo
     permissions:
-      id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
-          filter: blob:none
-          fetch-depth: 0
-      - uses: actions/setup-python@v4
-        with:
-          python-version: "3.x"
-          cache: "pip"
-      - run: pip install build
-      - run: python -m build
-      - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/test.yaml

@@ -5,56 +5,59 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
-  schedule:
-    - cron: "0 5 1,15 * *"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
   test:
-    runs-on: ${{ matrix.os }}
-    defaults:
-      run:
-        shell: bash -e {0} # -e to fail on error
-
+    runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.10", "3.11", "3.12"]
-        os: [ubuntu-latest]
-
+        python: ["3.11", "3.12"]
     env:
-      OS: ${{ matrix.os }}
-      PYTHON: ${{ matrix.python }}
-
+      JAX_PLATFORM_NAME: cpu
+      MPLBACKEND: Agg
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python ${{ matrix.python }}
-        uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
-          cache: "pip"
-          cache-dependency-path: "**/pyproject.toml"
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --locked --group test
+      - run: uv run pytest
+
+  clean-import:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v5
+      - run: uv venv /tmp/perturbo-base
+      - run: uv pip install --python /tmp/perturbo-base/bin/python .
+      - run: >-
+          /tmp/perturbo-base/bin/python -c
+          "import sys; import perturbo;
+          assert all(name not in sys.modules for name in ('torch', 'pyro', 'scvi'))"
 
-      - name: Install test dependencies
-        run: |
-          python -m pip install --upgrade pip wheel
-      - name: Install dependencies
-        run: |
-          pip install ".[dev,test]"
-      - name: Test
-        env:
-          MPLBACKEND: agg
-          PLATFORM: ${{ matrix.os }}
-          DISPLAY: :42
-        run: |
-          coverage run -m pytest -v --color=yes
-      - name: Report coverage
-        run: |
-          coverage report
-      - name: Upload coverage
-        uses: codecov/codecov-action@v3
+  legacy:
+    runs-on: ubuntu-latest
+    env:
+      JAX_PLATFORM_NAME: cpu
+      MPLBACKEND: Agg
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v5
         with:
-          token: ${{ secrets.CODECOV_TOKEN }}
+          enable-cache: true
+      - run: uv sync --locked --group test --extra legacy
+      - run: uv run pytest tests/legacy

.readthedocs.yaml

@@ -1,9 +1,9 @@
 # https://docs.readthedocs.io/en/stable/config-file/v2.html
 version: 2
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.10"
+    python: "3.11"
 sphinx:
   configuration: docs/conf.py
   # disable this for more lenient docs builds
@@ -13,4 +13,4 @@ python:
     - method: pip
       path: .
       extra_requirements:
-        - doc
+        - docs

CHANGELOG.md

@@ -12,4 +12,13 @@ and this project adheres to [Semantic Versioning][].
 
 ### Added
 
--   Basic tool, preprocessing and plotting functions
+-   PerTurbo 2.0 replaces the default implementation with NumPyro/JAX.
+-   The former PyTorch/Pyro/scvi implementation is isolated under the deprecated
+    `perturbo.legacy` optional extra.
+-   Cortado-format MuData registrations and fit bundles are read compatibly and
+    migrated to the PerTurbo v2 format when saved.
+
+### Changed
+
+-   Python 3.11 is now the minimum supported version.
+-   The command-line entry point is `perturbo`.

Dockerfile

@@ -1,13 +1,28 @@
-# syntax=docker/dockerfile:1
-FROM pytorch/pytorch:2.6.0-cuda12.4-cudnn9-runtime
+# JAX's CUDA 12 extra carries the CUDA/cuDNN user-space libraries as Python
+# wheels. The host's NVIDIA driver is supplied at runtime by the NVIDIA
+# Container Toolkit, so a PyTorch or system-CUDA base image is unnecessary.
+FROM python:3.11-slim
+
 WORKDIR /app
-ENV DEBIAN_FRONTEND=noninteractive
-RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates && rm -rf /var/lib/apt/lists/*
-RUN pip install --upgrade pip
 
-# The workflow will place PerTurbo/ alongside this Dockerfile
-COPY . /app/PerTurbo
-# (optional) avoid copying .git via .dockerignore
-RUN pip install /app/PerTurbo
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PYTHONUNBUFFERED=1 \
+    XLA_PYTHON_CLIENT_PREALLOCATE=false
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN python -m pip install --upgrade pip \
+    && python -m pip install uv==0.6.3
+
+COPY pyproject.toml uv.lock README.md LICENSE ./
+COPY src ./src
+
+RUN uv sync --locked --no-dev --extra cuda
+
+ENV PATH="/app/.venv/bin:$PATH"
 
-CMD ["python3"]
+ENTRYPOINT ["perturbo"]
+CMD ["--help"]