release: AtomWorks 3.0.0

.env.sample

@@ -22,8 +22,8 @@ PDB_MIRROR_PATH=
 # Example: /path/to/ccd_mirror/M/MYLIGAND1/MYLIGAND1.cif
 CCD_MIRROR_PATH=
 
-# --- Local MSA directories ---
-LOCAL_MSA_DIRS=
+# --- MSA directories ---
+PROTEIN_MSA_DIRS=
 
 
 # --- External tools ---
@@ -37,6 +37,20 @@ X3DNA_PATH=
 # Example: /path/to/hhsuite/build/bin/hhfilter
 HHFILTER_PATH=
 
+# The `HHBLITS_PATH` is a path to the hhblits tool from the HH-suite, which is used for
+# CPU-based MSA generation (--backend hhblits).
+# Example: /path/to/hhsuite/build/bin/hhblits
+HHBLITS_PATH=
+
+# HH-suite database paths (required for --backend hhblits)
+# UniRef30 database for HHblits
+# Example: /local/databases/uniclust/UniRef30_2022_02
+HHBLITS_UNIREF30_DB_PATH=
+
+# BFD database for HHblits (used as fallback when UniRef30 yields insufficient sequences)
+# Example: /local/databases/bfd/bfd_metaclust_clu_complete_id30_c90_final_seq.sorted_opt
+HHBLITS_BFD_DB_PATH=
+
 # The `MMSEQS2_PATH` is a path to the mmseqs2 tool, which is used for fast sequence searching.
 # Example: /path/to/mmseqs-gpu/bin/mmseqs
 MMSEQS2_PATH=

.github/ci/run_tests.sh

@@ -4,22 +4,41 @@ echo "Running from $PWD"
 
 export OPENBLAS_NUM_THREADS=1
 export OMP_NUM_THREADS=1
-apptainer_path=/net/software/containers/users/ncorley/atomworks/atomworks_dev.sif
-tar -xf /net/lab/pub/atomworks/test_pack_latest.tar.gz -C tests/data > /dev/null 2>&1
+: "${ATOMWORKS_CI_CONTAINER:?Set the AtomWorks CI container path}"
+: "${ATOMWORKS_CI_TEST_PACK:?Set the AtomWorks CI test-pack path}"
+
+# Give the container a job-local /tmp instead of the compute node's.
+ci_tmp=$(mktemp -d "$PWD/.ci-tmp.XXXXXX")
+trap 'rm -rf "$ci_tmp"' EXIT
+
+run_in_container() {
+    apptainer exec \
+        --bind "$PWD:/workspace" \
+        --bind "$ci_tmp:/tmp" \
+        --pwd /workspace \
+        --env PYTHONPATH=/workspace/src \
+        --env TMPDIR=/tmp \
+        "$ATOMWORKS_CI_CONTAINER" "$@"
+}
+
+# Extract the shared test pack (non-PDB fixtures). The PDB mirror itself is
+# resolved by tests/conftest.py, which prefers the lab-wide frozen PDB copy.
+mkdir -p tests/data
+tar -xf "$ATOMWORKS_CI_TEST_PACK" -C tests/data
 
 # Get max processes from environment variable, default to 24 if not set
 N_CPU=${N_CPU:-24}
 echo "Running tests with max $N_CPU CPUs"
 
 # Ensure we can collect all tests (i.e. imports succeed)
 echo "Testing imports by trying to collect all tests"
-apptainer exec --bind $PWD:/workspace --pwd /workspace --env PYTHONPATH=/workspace/src $apptainer_path pytest -m "not benchmark" --collect-only tests/
+run_in_container pytest -m "not benchmark" --collect-only tests/
 
 # Run the tests in coverage mode (with 24 CPUs)
-apptainer exec --bind $PWD:/workspace --pwd /workspace --env PYTHONPATH=/workspace/src $apptainer_path pytest -m "not benchmark" --cov=atomworks --cov-report=xml -n=auto --maxprocesses=$N_CPU --dist=worksteal tests/
+run_in_container pytest -m "not benchmark" --cov=atomworks --cov-report=xml -n=auto --maxprocesses=$N_CPU --dist=worksteal tests/
 
 # Require at least 80% coverage
-apptainer exec --bind $PWD:/workspace --pwd /workspace --env PYTHONPATH=/workspace/src $apptainer_path coverage report --fail-under=80
+run_in_container coverage report --fail-under=80
 
 # Output the coverage in a format GitLab can parse
-apptainer exec --bind $PWD:/workspace --pwd /workspace --env PYTHONPATH=/workspace/src $apptainer_path coverage report | tail -n 1 | awk '{print "TOTAL", $NF}'
+run_in_container coverage report | tail -n 1 | awk '{print "TOTAL", $NF}'

.github/pull_request_template.md

@@ -1,19 +1,13 @@
 ## 📋 PR Checklist
 
 - [ ] This PR is tagged as a [draft](https://github.blog/news-insights/product-news/introducing-draft-pull-requests/) if it is still under development and not ready for review. 
-    > This avoids auto-triggering the slower tests in the CI and needlessly wasting resources.
+    > Drafts still run CI.
 
 - [ ] I have ensured that all my commits follow [angular commit message conventions](https://www.conventionalcommits.org/en/v1.0.0-beta.4/).
     > Format: `<type>[optional scope]: <subject>`  
     > Example: `fix(af3): add missing crop transform to the af3 pipeline`
     >
-    > This affects semantic versioning as follows:
-    > - `fix`: patch version increment (0.0.1 → 0.0.2)
-    > - `feat`: minor version increment (0.0.1 → 0.1.0) 
-    > - `BREAKING CHANGE`: major version increment (0.0.1 → 1.0.0)
-    > - All other types do not affect versioning
-    >
-    > The format ensures readable changelogs through auto-generation from commit messages.
+    > Releases use the explicit version in `pyproject.toml` and a matching `v<version>` tag.
 
 - [ ] I have run `make format` on the codebase before submitting the PR (this autoformats the code and lints it).
 

.github/release.py

@@ -0,0 +1,101 @@
+"""Validate AtomWorks release tags and prepare versioned documentation."""
+
+import json
+import os
+import shutil
+import sys
+import tarfile
+import tomllib
+import zipfile
+from pathlib import Path
+
+from packaging.version import Version
+
+DOCS_URL = "https://rosettacommons.github.io/atomworks"
+
+
+def verify_distributions(dist: Path, source: Path) -> None:
+    """Require every package source and data file in both release archives, byte for byte."""
+    (wheel,) = dist.glob("*.whl")
+    (sdist,) = dist.glob("*.tar.gz")
+    files = [path for path in source.rglob("*") if path.is_file() and "__pycache__" not in path.parts]
+    if not files:
+        raise ValueError(f"No package files found in {source}")
+    with zipfile.ZipFile(wheel) as binary, tarfile.open(sdist) as archive:
+        for path in files:
+            relative = path.relative_to(source).as_posix()
+            member = f"{sdist.name.removesuffix('.tar.gz')}/src/{relative}"
+            archived = archive.extractfile(member)
+            expected = path.read_bytes()
+            if archived is None or archived.read() != expected or binary.read(relative) != expected:
+                raise ValueError(f"Release archive differs from source: {relative}")
+
+
+def release_version(tag: str) -> Version:
+    """Accept canonical version tags suitable for a public package release."""
+    version = Version(tag.removeprefix("v"))
+    if tag != f"v{version}" or version.is_devrelease or version.local:
+        raise ValueError(f"Expected a canonical release tag, got {tag!r}")
+    return version
+
+
+def verify_tag(tag: str, project_file: Path) -> Version:
+    """Require the release tag to match the package's declared version exactly."""
+    version = release_version(tag)
+    project_version = tomllib.loads(project_file.read_text())["project"]["version"]
+    if tag != f"v{project_version}":
+        raise ValueError(f"Tag {tag!r} does not match project.version {project_version!r}")
+    return version
+
+
+def prepare_docs(tag: str, html: Path, pages: Path) -> None:
+    """Keep published version pages intact and point latest at the newest stable release."""
+    release_version(tag)
+    if not (html / "index.html").is_file():
+        raise FileNotFoundError(f"Documentation index missing from {html}")
+    destination = pages / tag
+    if not destination.exists():
+        shutil.copytree(html, destination)
+    versions = []
+    for directory in pages.iterdir():
+        if not directory.is_dir() or not (directory / "index.html").is_file():
+            continue
+        try:
+            version = release_version(directory.name)
+        except ValueError:
+            continue
+        versions.append((version, directory.name))
+    versions.sort(reverse=True)
+    stable = next((name for version, name in versions if not version.is_prerelease), None)
+    latest = pages / "latest"
+    if stable:
+        if latest.exists():
+            shutil.rmtree(latest)
+        shutil.copytree(pages / stable, latest)
+    switcher = [{"version": "latest", "url": f"{DOCS_URL}/latest/index.html", "name": "latest"}] if stable else []
+    switcher.extend(
+        {"version": str(version), "url": f"{DOCS_URL}/{name}/index.html", "name": name, "preferred": name == stable}
+        for version, name in versions
+    )
+    targets = [pages, *(pages / name for _, name in versions)]
+    if stable:
+        targets.append(latest)
+    for directory in targets:
+        switcher_path = directory / "_static" / "switcher.json"
+        switcher_path.parent.mkdir(parents=True, exist_ok=True)
+        switcher_path.write_text(json.dumps(switcher, indent=2) + "\n")
+
+
+if __name__ == "__main__":
+    if sys.argv[1:] == ["artifacts"]:
+        verify_distributions(Path("dist"), Path("src"))
+        raise SystemExit(0)
+    tag = os.environ["GITHUB_REF_NAME"]
+    version = verify_tag(tag, Path("pyproject.toml"))
+    if sys.argv[1:] == ["verify"]:
+        with Path(os.environ["GITHUB_OUTPUT"]).open("a") as output:
+            output.write(f"prerelease={str(version.is_prerelease).lower()}\n")
+    elif sys.argv[1:] == ["docs"]:
+        prepare_docs(tag, Path("docs/_build/html"), Path("gh-pages"))
+    else:
+        raise SystemExit("Usage: python .github/release.py {verify|docs|artifacts}")

.github/tests/test_release.py

@@ -0,0 +1,98 @@
+"""Check package contents, tag consistency, and docs promotion without publishing."""
+
+import json
+import sys
+import tarfile
+import tempfile
+import unittest
+import zipfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from release import prepare_docs, verify_distributions, verify_tag
+
+
+class ReleaseTests(unittest.TestCase):
+    def setUp(self) -> None:  # noqa: N802
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.root = Path(self.temp.name)
+        self.project = self.root / "pyproject.toml"
+        self.html = self.root / "html"
+        self.html.mkdir()
+        (self.html / "index.html").write_text("new documentation")
+        self.pages = self.root / "pages"
+        self.pages.mkdir()
+
+    def test_tag_must_match_project_version(self) -> None:
+        for value in ("2.3.0", "2.3.0rc1"):
+            with self.subTest(value=value):
+                self.project.write_text(f'[project]\nversion = "{value}"\n')
+                self.assertEqual(str(verify_tag(f"v{value}", self.project)), value)
+                with self.assertRaises(ValueError):
+                    verify_tag("v9.0.0", self.project)
+
+    def test_distribution_contents(self) -> None:
+        source = self.root / "src"
+        package = source / "atomworks"
+        package.mkdir(parents=True)
+        (package / "__init__.py").write_text('"""AtomWorks."""\n')
+        (package / "parameters.json").write_text('{"charge": -1}\n')
+        dist = self.root / "dist"
+        dist.mkdir()
+        for case in ("complete", "empty-wheel", "missing-data", "changed-data", "relocated-source"):
+            with self.subTest(case=case):
+                with zipfile.ZipFile(dist / "atomworks-2.3.0-py3-none-any.whl", "w") as wheel:
+                    for path in package.iterdir():
+                        if case == "empty-wheel" or (case == "missing-data" and path.suffix == ".json"):
+                            continue
+                        data = b"{}" if case == "changed-data" and path.suffix == ".json" else path.read_bytes()
+                        wheel.writestr(path.relative_to(source).as_posix(), data)
+                with tarfile.open(dist / "atomworks-2.3.0.tar.gz", "w:gz") as archive:
+                    prefix = "" if case == "relocated-source" else "src/"
+                    archive.add(package, arcname=f"atomworks-2.3.0/{prefix}atomworks")
+                if case == "complete":
+                    verify_distributions(dist, source)
+                else:
+                    with self.assertRaises((KeyError, ValueError)):
+                        verify_distributions(dist, source)
+
+    def test_rejects_nonrelease_tags(self) -> None:
+        self.project.write_text('[project]\nversion = "2.3.0"\n')
+        for tag in ("2.3.0", "production", "v2.3.0.dev1", "v2.3.0+local", "v2.3.0/extra"):
+            with self.subTest(tag=tag), self.assertRaises(ValueError):
+                verify_tag(tag, self.project)
+
+    def test_old_release_and_prerelease_do_not_replace_latest(self) -> None:
+        for version in ("v2.2.10", "v2.2.9", "v2.3.0rc1"):
+            (self.html / "index.html").write_text(version)
+            prepare_docs(version, self.html, self.pages)
+        self.assertEqual((self.pages / "latest/index.html").read_text(), "v2.2.10")
+        switcher = json.loads((self.pages / "_static/switcher.json").read_text())
+        self.assertEqual([entry["name"] for entry in switcher], ["latest", "v2.3.0rc1", "v2.2.10", "v2.2.9"])
+        self.assertEqual([entry["name"] for entry in switcher if entry.get("preferred")], ["v2.2.10"])
+        self.assertEqual(switcher, json.loads((self.pages / "v2.2.9/_static/switcher.json").read_text()))
+
+    def test_new_stable_release_updates_latest_without_stale_files(self) -> None:
+        prepare_docs("v2.0.0", self.html, self.pages)
+        (self.pages / "latest/removed.html").write_text("old page")
+        (self.html / "index.html").write_text("new stable")
+        prepare_docs("v2.3.0", self.html, self.pages)
+        self.assertEqual((self.pages / "latest/index.html").read_text(), "new stable")
+        self.assertFalse((self.pages / "latest/removed.html").exists())
+
+    def test_retry_preserves_published_version_pages(self) -> None:
+        prepare_docs("v2.3.0", self.html, self.pages)
+        (self.html / "index.html").write_text("different build")
+        prepare_docs("v2.3.0", self.html, self.pages)
+        self.assertEqual((self.pages / "v2.3.0/index.html").read_text(), "new documentation")
+
+    def test_first_prerelease_has_switcher_without_stable_alias(self) -> None:
+        prepare_docs("v2.3.0rc1", self.html, self.pages)
+        self.assertFalse((self.pages / "latest").exists())
+        switcher = json.loads((self.pages / "_static/switcher.json").read_text())
+        self.assertEqual([entry["name"] for entry in switcher], ["v2.3.0rc1"])
+
+
+if __name__ == "__main__":
+    unittest.main()