Standardizing Python project setup using uv

.github/actions/python-uv-setup/action.yml

@@ -1,5 +1,6 @@
 name: "python-uv-setup"
 description: "Common Python + uv setup, deps install, and optional debug"
+
 inputs:
   python-version:
     description: "Python version"
@@ -8,6 +9,18 @@ inputs:
     description: "Enable debug output"
     required: false
     default: "false"
+  lockfile:
+    description: "Lockfile to use"
+    required: false
+    default: "uv.lock.cpu"
+  extras:
+    description: "Extra dependency set to install"
+    required: false
+    default: "cpu"
+  dependency-groups:
+    description: "Dependency group to install"
+    required: false
+    default: "dev"
 
 runs:
   using: "composite"
@@ -40,34 +53,22 @@ runs:
       uses: actions/cache@v4
       with:
         path: ~/.cache/uv
-        key: ${{ runner.os }}-uv-${{ hashFiles('pip/*.txt') }}
+        key: ${{ runner.os }}-py${{ inputs.python-version }}-uv-${{ hashFiles('pyproject.toml', 'uv.lock.cpu') }}
         restore-keys: |
-          ${{ runner.os }}-uv-
-
-    - name: Create virtual environment
-      shell: bash
-      run: |
-        uv venv --seed .venv
+          ${{ runner.os }}-py${{ inputs.python-version }}-uv-
 
     - name: Install dependencies
       shell: bash
       run: |
         set -euxo pipefail
+        cp "${{ inputs.lockfile }}" uv.lock
+        uv venv .venv
         . .venv/bin/activate
-
-        which python
-        python -V
-
-        uv pip install -e .
-        if [ -f pip/cpu_requirements.txt ]; then uv pip install -r pip/cpu_requirements.txt; fi
-        if [ -f pip/dev_requirements.txt ]; then uv pip install -r pip/dev_requirements.txt; fi
+        uv sync --extra "${{ inputs.extras }}" --group "${{ inputs.dependency-groups }}" --locked
 
     - name: Debug - what is installed
       if: ${{ inputs.debug == 'true' }}
       shell: bash
       run: |
         . .venv/bin/activate
-        python -m pip --version
-        python -V
-        uv --version
-        uv pip list
+        uv pip list

.github/workflows/build.yml

@@ -1,8 +1,34 @@
+# How to run manually:
+# 1. Go to the GitHub repository.
+# 2. Click the "Actions" tab.
+# 3. Select this workflow, "docker publish".
+# 4. Click "Run workflow".
+# 5. Choose the desired inputs, then click "Run workflow".
+
 name: docker publish
 
 on:
-  release:
-    types: [published]
+  workflow_dispatch:
+    inputs:
+      env:
+        description: "Deployment environment"
+        required: true
+        default: "prod"
+        type: choice
+        options:
+          - prod
+          - staging
+      target:
+        description: "Which image(s) to build"
+        required: true
+        default: "all"
+        type: choice
+        options:
+          - all
+          - gpu
+          - rocm
+          - cpu-amd64
+          - cpu-arm64
 
 jobs:
   build-and-push:
@@ -11,10 +37,19 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # Uses Dockerfile.gpu
           - name: gpu
             platform: gpu
+            arch: ""
+          # Uses Dockerfile.rocm
+          - name: rocm
+            platform: rocm
+            arch: ""
+          # Uses Dockerfile.cpu
           - name: cpu-amd64
             platform: cpu
+            arch: ""
+          # Uses Dockerfile.arm
           - name: cpu-arm64
             platform: arm
             arch: linux/arm64
@@ -34,14 +69,14 @@ jobs:
           password: ${{ secrets.DOCKER_PASSWORD }}
 
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 1
 
       - name: Build and push Docker image
-        run: |
-          make push-docker
+        if: ${{ github.event.inputs.target == 'all' || github.event.inputs.target == matrix.name }}
+        run: make push-docker
         env:
-          ENV: prod
+          ENV: ${{ github.event.inputs.env }}
           PLATFORM: ${{ matrix.platform }}
           ARCH: ${{ matrix.arch }}

.github/workflows/publish.yml

@@ -0,0 +1,131 @@
+name: Publish Python Package
+
+# Publish atomsci-ampl to TestPyPI and PyPI
+#
+# Owner           -> ATOMScience-org
+# Repository name -> AMPL
+# Project         -> atomsci-ampl
+#
+# This workflow is manual only.
+#
+# Workflow behavior:
+#
+# 1. Build the package distribution
+# 2. Optionally publish to TestPyPI
+# 3. Optionally publish to PyPI
+#
+# How to use:
+#
+# - Run this workflow manually from the GitHub Actions tab
+# - Choose whether to publish to TestPyPI
+# - Choose whether to publish to PyPI
+#
+# Notes:
+#
+# - Package versions cannot be reused once published
+# - For TestPyPI testing, use development version names such as:
+#
+#     1.2.3.dev1
+#
+# - If you want PyPI publication to require approval, configure
+#   protection rules on the "pypi" environment
+#
+# Recommended usage:
+#
+# - TestPyPI only:
+#     publish_testpypi = true
+#     publish_pypi     = false
+#
+# - TestPyPI and PyPI:
+#     publish_testpypi = true
+#     publish_pypi     = true
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish_testpypi:
+        description: "Publish to TestPyPI"
+        required: true
+        type: boolean
+        default: true
+      publish_pypi:
+        description: "Publish to PyPI"
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  # Job 1: Build the source distribution and wheel
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  # Job 2: Optionally publish to TestPyPI
+  publish-test:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: ${{ inputs.publish_testpypi }}
+    environment: testpypi
+
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          user: __token__
+          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+
+  # Job 3: Optionally publish to PyPI
+  # This runs only if PyPI publishing was selected.
+  # It also depends on the TestPyPI job, so TestPyPI must be selected too.
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: publish-test
+    if: ${{ inputs.publish_testpypi && inputs.publish_pypi }}
+    environment: pypi
+
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/pytest.yml

@@ -20,14 +20,24 @@ jobs:
       - uses: ./.github/actions/python-uv-setup
         with:
           python-version: ${{ matrix.python-version }}
+          lockfile: uv.lock.cpu
+          extras: cpu
+          dependency-groups: dev
           debug: "false"
 
-      - name: pytest
+      - name: Run modac unit tests
         shell: bash
+        working-directory: atomsci/modac/test/unit
         run: |
-          . .venv/bin/activate
-          cd atomsci/modac/test/unit && python -m pytest --capture=sys --capture=fd --cov=atomsci/ -vv
-          cd "${{ github.workspace }}/atomsci/ddm/test/unit" && python -m pytest -m "not moe_required" -n 2 --capture=fd --cov=atomsci -vv --durations=4 --durations-min=0.05
+          . "${{ github.workspace }}/.venv/bin/activate"
+          python -m pytest --capture=sys --capture=fd --cov=atomsci/ -vv
+
+      - name: Run ddm unit tests
+        shell: bash
+        working-directory: atomsci/ddm/test/unit
+        run: |
+          . "${{ github.workspace }}/.venv/bin/activate"
+          python -m pytest -m "not moe_required" -n 2 --capture=fd --cov=atomsci -vv --durations=4 --durations-min=0.05
 
       - name: Save coverage
         uses: actions/upload-artifact@v4
@@ -56,13 +66,16 @@ jobs:
       - uses: ./.github/actions/python-uv-setup
         with:
           python-version: ${{ matrix.python-version }}
+          lockfile: uv.lock.cpu
+          extras: cpu
+          dependency-groups: dev
           debug: "false"
 
       - name: Debug - dgl + torchdata + shadowing
         shell: bash
         if: ${{ env.DEBUG_DGL == 'true' }}
         run: |
-          . .venv/bin/activate
+          . "${{ github.workspace }}/.venv/bin/activate"
           set -x
 
           which python
@@ -76,11 +89,11 @@ jobs:
           python -m pip show torch torchdata dgl dgllife || true
           python -m pip freeze | grep -E '^(torch|torchdata|dgl|dgllife|numpy)=' || true
 
-      - name: pytest
+      - name: Run integrative tests
         shell: bash
+        working-directory: atomsci/ddm/test/integrative
         run: |
-          . .venv/bin/activate
-          cd atomsci/ddm/test/integrative
+          . "${{ github.workspace }}/.venv/bin/activate"
           ./integrative_batch_chunk_tests ${{ matrix.chunk }}
 
       - name: Save coverage

.gitignore

@@ -123,6 +123,8 @@ celerybeat.pid
 # Environments
 .env
 .venv
+.venv-*
+uv.lock
 env/
 venv/
 ENV/

.readthedocs.yml

@@ -1,14 +1,21 @@
 # .readthedocs.yml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+#
 
-# Required
-version: 1
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
 
-# Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/source/conf.py
 
-# Optionally set the version of Python and requirements required to build your docs
 python:
-   version: 3.7
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

CONTRIBUTING.md

@@ -50,7 +50,19 @@ git fetch upstream
 git rebase upstream/master
 ```
 
-2. Set up a new environment for AMPL by following these [instructions](https://github.com/ATOMScience-org/AMPL#install).
+2. Set up a new environment for AMPL by following these [instructions](https://github.com/ATOMScience-org/AMPL#installation).
+
+This project uses [`uv`](https://docs.astral.sh/uv/) (a fast Python package and project manager) together with `pyproject.toml` and `uv.lock` for dependency management.
+
+### Prerequisites
+- Install **uv** (recommended way):
+  ```bash
+  # On macOS / Linux
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+
+  # On Windows (PowerShell)
+  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+  ```
 
 Keep in mind, every contribution must pass the unit tests.