openfold3-accel 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. openfold3_accel-0.1.0/CHANGELOG.md +14 -0
  2. openfold3_accel-0.1.0/LICENSE +1 -0
  3. openfold3_accel-0.1.0/MANIFEST.in +1 -0
  4. openfold3_accel-0.1.0/PKG-INFO +65 -0
  5. openfold3_accel-0.1.0/README.md +24 -0
  6. openfold3_accel-0.1.0/pyproject.toml +69 -0
  7. openfold3_accel-0.1.0/setup.cfg +4 -0
  8. openfold3_accel-0.1.0/src/openfold3_accel/__init__.py +153 -0
  9. openfold3_accel-0.1.0/src/openfold3_accel/_cache.py +202 -0
  10. openfold3_accel-0.1.0/src/openfold3_accel/_compat.py +84 -0
  11. openfold3_accel-0.1.0/src/openfold3_accel/_patch.py +210 -0
  12. openfold3_accel-0.1.0/src/openfold3_accel/_selfcheck.py +89 -0
  13. openfold3_accel-0.1.0/src/openfold3_accel/bench/__init__.py +0 -0
  14. openfold3_accel-0.1.0/src/openfold3_accel/bench/__main__.py +98 -0
  15. openfold3_accel-0.1.0/src/openfold3_accel/bench/core.py +202 -0
  16. openfold3_accel-0.1.0/src/openfold3_accel/bench/report.py +143 -0
  17. openfold3_accel-0.1.0/src/openfold3_accel/patches/__init__.py +17 -0
  18. openfold3_accel-0.1.0/src/openfold3_accel/patches/attention.py +58 -0
  19. openfold3_accel-0.1.0/src/openfold3_accel/patches/bf16.py +132 -0
  20. openfold3_accel-0.1.0/src/openfold3_accel/patches/diffusion.py +459 -0
  21. openfold3_accel-0.1.0/src/openfold3_accel/patches/loading.py +50 -0
  22. openfold3_accel-0.1.0/src/openfold3_accel/py.typed +0 -0
  23. openfold3_accel-0.1.0/src/openfold3_accel.egg-info/PKG-INFO +65 -0
  24. openfold3_accel-0.1.0/src/openfold3_accel.egg-info/SOURCES.txt +27 -0
  25. openfold3_accel-0.1.0/src/openfold3_accel.egg-info/dependency_links.txt +1 -0
  26. openfold3_accel-0.1.0/src/openfold3_accel.egg-info/entry_points.txt +3 -0
  27. openfold3_accel-0.1.0/src/openfold3_accel.egg-info/requires.txt +22 -0
  28. openfold3_accel-0.1.0/src/openfold3_accel.egg-info/top_level.txt +1 -0
  29. openfold3_accel-0.1.0/tests/test_equivalence.py +480 -0
@@ -0,0 +1,14 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0
4
+ - Review round 2: `disable()` is atomic (dry run first; if third-party code wrapped any installed patch, nothing is reverted and groups stay `active`, with a warning); bf16 wrappers also require the weights to be on CPU, so accelerator runs never enter CPU autocast or touch `requires_grad`; tests for third-party wrapping, re-apply failure and the off-CPU bypass.
5
+ - Review fixes: selective `disable()` of an inner group now rebuilds the wrapper stack (and never reports a still-installed patch as inactive); the self-check preserves torch/NumPy/Python RNG state; bf16 rollouts hold a lock and have an `OPENFOLD3_ACCEL_NO_CASTCACHE=1` opt-out; tests added for every enable/disable order, RNG preservation, threads, odd sizes, batch>1, masked atoms and a tiny cache budget.
6
+ - Kit-inspired additions (independent implementations; see prior art): pre-summed attention biases (default group), bf16 autocast weight-cast cache, opt-in `fast_init` and `fused_attention` groups; bench gains `exact+fused`, `exact+fused+bf16`, `init:*` modes.
7
+ - Group revert now unwinds in reverse order so stacked wrappers restore cleanly.
8
+ - Fix: cache no longer crashes under `torch.inference_mode()` (Lightning `Trainer.predict`); tensors without version counters are matched by identity.
9
+ - Real import-time self-check (replaces a stub); bf16 group now checks for AMX/AVX512-BF16 and falls back to fp32 with a warning.
10
+ - Supported range narrowed to `openfold3>=0.5.0,<0.6` (0.4.x fingerprints differ); CI covers 0.5.0 and 0.5.1.
11
+ - Tests assert every cache path is exercised and cover inference mode; bench reports Kabsch-aligned RMSD.
12
+ - Docs: prior-art page and evidence caveats.
13
+ - Tracing/export (ONNX, TorchScript, `torch.export`, `torch.compile`) bypass: upstream code runs.
14
+ - Initial release: diffusion_cache (exact), bf16_diffusion (opt-in).
@@ -0,0 +1 @@
1
+ Apache-2.0 (see https://www.apache.org/licenses/LICENSE-2.0). Replace with full text before release.
@@ -0,0 +1 @@
1
+ include README.md LICENSE CHANGELOG.md
@@ -0,0 +1,65 @@
1
+ Metadata-Version: 2.4
2
+ Name: openfold3-accel
3
+ Version: 0.1.0
4
+ Summary: Drop-in, reversible inference acceleration for OpenFold3 (CPU-focused): `import openfold3_accel`.
5
+ Author: Eachan Johnson
6
+ License: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/scbirlab/openfold3-accel
8
+ Project-URL: Documentation, https://scbirlab.github.io/openfold3-accel/
9
+ Project-URL: Issues, https://github.com/scbirlab/openfold3-accel/issues
10
+ Keywords: openfold3,alphafold3,pytorch,structure prediction,performance,cpu
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: License :: OSI Approved :: Apache Software License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
19
+ Requires-Python: <3.15,>=3.12
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: torch>=2.5
23
+ Provides-Extra: openfold3
24
+ Requires-Dist: openfold3<0.6,>=0.5.0; extra == "openfold3"
25
+ Provides-Extra: test
26
+ Requires-Dist: pytest>=8; extra == "test"
27
+ Requires-Dist: pytest-cov; extra == "test"
28
+ Requires-Dist: openfold3<0.6,>=0.5.0; extra == "test"
29
+ Provides-Extra: docs
30
+ Requires-Dist: sphinx>=7.3; extra == "docs"
31
+ Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
32
+ Requires-Dist: myst-parser>=3; extra == "docs"
33
+ Requires-Dist: sphinx-copybutton; extra == "docs"
34
+ Requires-Dist: sphinx-design; extra == "docs"
35
+ Provides-Extra: dev
36
+ Requires-Dist: openfold3-accel[docs,test]; extra == "dev"
37
+ Requires-Dist: ruff; extra == "dev"
38
+ Requires-Dist: pre-commit; extra == "dev"
39
+ Requires-Dist: build; extra == "dev"
40
+ Dynamic: license-file
41
+
42
+ # openfold3-accel
43
+
44
+ Drop-in, **reversible** inference acceleration for [OpenFold3](https://github.com/aqlaboratory/openfold-3),
45
+ focused on multicore CPU.
46
+
47
+ ```python
48
+ import openfold3_accel # that's it
49
+ ```
50
+
51
+ - **Exact by default.** The default group removes work that is repeated on every diffusion step; outputs
52
+ match upstream (0.0 difference on valid atoms in our tests).
53
+ - **Opt-in groups:** `bf16_diffusion` (AMX/AVX512-BF16 CPUs, with weight-cast caching), `fast_init` (faster model construction), `fused_attention` (SDPA; no measured gain on 2 vCPU).
54
+ - **Safe.** Patches apply only to fingerprint-verified OpenFold3 sources, only with grads off and in `eval()`;
55
+ otherwise upstream code runs. `disable()` / `disabled()` revert in-process. Checkpoints unaffected.
56
+ - **Preliminary evidence:** on one 2-vCPU AMX Xeon, a synthetic rollout (random weights, diffusion only) ran 1.2× (exact)
57
+ and 1.8× (exact+bf16) faster. Not an end-to-end or trained-weights result; run `openfold3-accel-bench` yourself.
58
+ - **Prior art:** the core caching ideas exist in Boltz-1, Protenix and Anthropic's OpenFold3 kit; see the
59
+ docs' *Prior art* page. This package's contribution is a small, reversible, CPU-first packaging of them.
60
+
61
+ Docs: https://scbirlab.github.io/openfold3-accel/ · Licence: Apache-2.0
62
+
63
+ Install: `pip install openfold3-accel openfold3`. Supports `openfold3>=0.5.0,<0.6`, Python 3.12–3.14.
64
+ Note: on CPU-only hosts, set `use_triton_triangle_kernels: false` in the runner config (upstream default
65
+ tries Triton and fails without a GPU driver).
@@ -0,0 +1,24 @@
1
+ # openfold3-accel
2
+
3
+ Drop-in, **reversible** inference acceleration for [OpenFold3](https://github.com/aqlaboratory/openfold-3),
4
+ focused on multicore CPU.
5
+
6
+ ```python
7
+ import openfold3_accel # that's it
8
+ ```
9
+
10
+ - **Exact by default.** The default group removes work that is repeated on every diffusion step; outputs
11
+ match upstream (0.0 difference on valid atoms in our tests).
12
+ - **Opt-in groups:** `bf16_diffusion` (AMX/AVX512-BF16 CPUs, with weight-cast caching), `fast_init` (faster model construction), `fused_attention` (SDPA; no measured gain on 2 vCPU).
13
+ - **Safe.** Patches apply only to fingerprint-verified OpenFold3 sources, only with grads off and in `eval()`;
14
+ otherwise upstream code runs. `disable()` / `disabled()` revert in-process. Checkpoints unaffected.
15
+ - **Preliminary evidence:** on one 2-vCPU AMX Xeon, a synthetic rollout (random weights, diffusion only) ran 1.2× (exact)
16
+ and 1.8× (exact+bf16) faster. Not an end-to-end or trained-weights result; run `openfold3-accel-bench` yourself.
17
+ - **Prior art:** the core caching ideas exist in Boltz-1, Protenix and Anthropic's OpenFold3 kit; see the
18
+ docs' *Prior art* page. This package's contribution is a small, reversible, CPU-first packaging of them.
19
+
20
+ Docs: https://scbirlab.github.io/openfold3-accel/ · Licence: Apache-2.0
21
+
22
+ Install: `pip install openfold3-accel openfold3`. Supports `openfold3>=0.5.0,<0.6`, Python 3.12–3.14.
23
+ Note: on CPU-only hosts, set `use_triton_triangle_kernels: false` in the runner config (upstream default
24
+ tries Triton and fails without a GPU driver).
@@ -0,0 +1,69 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "openfold3-accel"
7
+ version = "0.1.0"
8
+ description = "Drop-in, reversible inference acceleration for OpenFold3 (CPU-focused): `import openfold3_accel`."
9
+ readme = "README.md"
10
+ requires-python = ">=3.12,<3.15"
11
+ license = { text = "Apache-2.0" }
12
+ authors = [{ name = "Eachan Johnson" }]
13
+ keywords = ["openfold3", "alphafold3", "pytorch", "structure prediction", "performance", "cpu"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Intended Audience :: Science/Research",
17
+ "License :: OSI Approved :: Apache Software License",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Programming Language :: Python :: 3.13",
21
+ "Programming Language :: Python :: 3.14",
22
+ "Topic :: Scientific/Engineering :: Bio-Informatics",
23
+ ]
24
+ dependencies = ["torch>=2.5"]
25
+
26
+ [project.optional-dependencies]
27
+ openfold3 = ["openfold3>=0.5.0,<0.6"]
28
+ test = ["pytest>=8", "pytest-cov", "openfold3>=0.5.0,<0.6"]
29
+ docs = [
30
+ "sphinx>=7.3",
31
+ "pydata-sphinx-theme>=0.15",
32
+ "myst-parser>=3",
33
+ "sphinx-copybutton",
34
+ "sphinx-design",
35
+ ]
36
+ dev = ["openfold3-accel[test,docs]", "ruff", "pre-commit", "build"]
37
+
38
+ [project.scripts]
39
+ openfold3-accel-bench = "openfold3_accel.bench.__main__:main"
40
+ openfold3-accel-report = "openfold3_accel.bench.report:main"
41
+
42
+ [project.urls]
43
+ Homepage = "https://github.com/scbirlab/openfold3-accel"
44
+ Documentation = "https://scbirlab.github.io/openfold3-accel/"
45
+ Issues = "https://github.com/scbirlab/openfold3-accel/issues"
46
+
47
+ [tool.setuptools.packages.find]
48
+ where = ["src"]
49
+
50
+ [tool.setuptools.package-data]
51
+ openfold3_accel = ["py.typed"]
52
+
53
+ [tool.pytest.ini_options]
54
+ testpaths = ["tests"]
55
+ addopts = "-ra --strict-markers"
56
+ markers = ["slow: slower end-to-end tests"]
57
+ filterwarnings = ["ignore::DeprecationWarning", "ignore::UserWarning"]
58
+
59
+ [tool.ruff]
60
+ line-length = 100
61
+ target-version = "py312"
62
+ src = ["src", "tests"]
63
+
64
+ [tool.ruff.lint]
65
+ select = ["E", "F", "I", "UP", "B", "W"]
66
+ ignore = ["E501", "B905"]
67
+
68
+ [tool.coverage.run]
69
+ source = ["openfold3_accel"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,153 @@
1
+ """Drop-in CPU-oriented inference acceleration for OpenFold3.
2
+
3
+ Usage::
4
+
5
+ import openfold3_accel # activates automatically (set OPENFOLD3_ACCEL_DISABLE=1 to prevent)
6
+ import openfold3 # (order does not matter; patches resolve lazily)
7
+
8
+ See :func:`status`, :func:`enable` and :func:`disable`.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import contextlib
14
+ import os
15
+ from collections.abc import Iterable, Iterator
16
+ from dataclasses import dataclass, field
17
+
18
+ from . import _compat, _patch, _selfcheck
19
+ from .patches import DEFAULT_GROUPS, group_defs
20
+
21
+ try:
22
+ from importlib.metadata import version as _version
23
+
24
+ __version__ = _version("openfold3-accel")
25
+ except Exception: # noqa: BLE001
26
+ __version__ = "0.0.0+unknown"
27
+
28
+ __all__ = [
29
+ "enable",
30
+ "disable",
31
+ "status",
32
+ "Status",
33
+ "enabled",
34
+ "disabled",
35
+ "groups",
36
+ "__version__",
37
+ ]
38
+
39
+
40
+ def groups() -> dict[str, str]:
41
+ """Available patch groups and a one-line description of each."""
42
+ return {name: summary for name, (summary, _make) in group_defs().items()}
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class Status:
47
+ """Snapshot returned by :func:`status`."""
48
+
49
+ enabled: bool
50
+ reason: str
51
+ openfold3_version: str | None
52
+ openfold3_supported: bool
53
+ openfold3_supported_range: str
54
+ torch_version: str
55
+ groups: dict[str, str] = field(default_factory=dict)
56
+ patches: dict[str, str] = field(default_factory=dict)
57
+
58
+ def __str__(self) -> str:
59
+ lines = [
60
+ f"openfold3_accel {__version__}: {'ENABLED' if self.enabled else 'disabled'} ({self.reason})",
61
+ f" openfold3: {self.openfold3_version} (supported {self.openfold3_supported_range}: "
62
+ f"{self.openfold3_supported})",
63
+ f" torch: {self.torch_version}",
64
+ ]
65
+ lines += [f" group {k}: {v}" for k, v in self.groups.items()]
66
+ lines += [f" patch {k}: {v}" for k, v in self.patches.items()]
67
+ return "\n".join(lines)
68
+
69
+
70
+ def _selected(selection: Iterable[str] | None) -> list[str]:
71
+ avail = list(group_defs())
72
+ if selection is not None:
73
+ names = list(selection)
74
+ else:
75
+ env = os.environ.get("OPENFOLD3_ACCEL_GROUPS", "")
76
+ names = [g.strip() for g in env.split(",") if g.strip()] or list(DEFAULT_GROUPS)
77
+ skip = {
78
+ g.strip() for g in os.environ.get("OPENFOLD3_ACCEL_SKIP", "").split(",") if g.strip()
79
+ }
80
+ names = [g for g in names if g not in skip]
81
+ unknown = [g for g in names if g not in avail]
82
+ if unknown:
83
+ raise ValueError(f"unknown patch group(s) {unknown}; available: {avail}")
84
+ return names
85
+
86
+
87
+ def enable(groups: Iterable[str] | None = None) -> Status:
88
+ """Apply the optimisations (idempotent). Unsupported setups are left untouched and reported.
89
+
90
+ Parameters
91
+ ----------
92
+ groups
93
+ Subset of :func:`groups` to enable. Default: all (honouring ``OPENFOLD3_ACCEL_GROUPS`` and
94
+ ``OPENFOLD3_ACCEL_SKIP``).
95
+ """
96
+ _patch.apply(group_defs(), _selected(groups), _selfcheck.run)
97
+ return status()
98
+
99
+
100
+ def disable(groups: Iterable[str] | None = None) -> Status:
101
+ """Restore the original OpenFold3 callables (removing stacked wrappers in a safe order)."""
102
+ for w in _patch.revert(groups):
103
+ import warnings
104
+
105
+ warnings.warn(w, RuntimeWarning, stacklevel=2)
106
+ return status()
107
+
108
+
109
+ @contextlib.contextmanager
110
+ def disabled(groups: Iterable[str] | None = None) -> Iterator[None]:
111
+ """Temporarily run upstream OpenFold3 code (e.g. for A/B comparisons), then re-enable."""
112
+ before = [n for n, g in _patch.STATE.groups.items() if g.state == "active"]
113
+ names = before if groups is None else [n for n in groups if n in before]
114
+ disable(names)
115
+ try:
116
+ yield
117
+ finally:
118
+ enable(names)
119
+
120
+
121
+ @contextlib.contextmanager
122
+ def enabled(groups: Iterable[str] | None = None) -> Iterator[None]:
123
+ """Temporarily enable (and afterwards restore) the optimisations."""
124
+ before = {n for n, g in _patch.STATE.groups.items() if g.state == "active"}
125
+ enable(groups)
126
+ try:
127
+ yield
128
+ finally:
129
+ now = [n for n, g in _patch.STATE.groups.items() if g.state == "active" and n not in before]
130
+ disable(now)
131
+
132
+
133
+ def status() -> Status:
134
+ import torch
135
+
136
+ v = _compat.openfold3_version()
137
+ ok, _ = _compat.version_supported(v)
138
+ lo = ".".join(map(str, _compat.MIN_OPENFOLD3))
139
+ hi = ".".join(map(str, _compat.MAX_OPENFOLD3_EXCLUSIVE))
140
+ return Status(
141
+ enabled=_patch.STATE.enabled,
142
+ reason=_patch.STATE.reason,
143
+ openfold3_version=v,
144
+ openfold3_supported=ok,
145
+ openfold3_supported_range=f">={lo},<{hi}",
146
+ torch_version=torch.__version__,
147
+ groups={k: g.state for k, g in _patch.STATE.groups.items()},
148
+ patches={p.name: p.state for g in _patch.STATE.groups.values() for p in g.patches},
149
+ )
150
+
151
+
152
+ if os.environ.get("OPENFOLD3_ACCEL_DISABLE", "") not in ("1", "true", "True", "yes"):
153
+ enable()
@@ -0,0 +1,202 @@
1
+ """Rollout-scoped memoisation of tensors that do not change between denoising steps.
2
+
3
+ OpenFold3's diffusion sampler calls the denoiser ~200 times per sample with *identical* trunk
4
+ conditioning (``zij``, ``si_trunk``, reference-conformer features, masks). Only the noisy
5
+ coordinates and the noise-level embedding change. Many sub-expressions of the denoiser depend only
6
+ on the static inputs (pair biases, ``LayerNorm(z)``, the atom-pair MLP, the ``s``-dependent half of
7
+ every atom-level adaptive layer-norm, ...). They are recomputed on every step by upstream code.
8
+
9
+ This module provides the small amount of machinery that lets patched layers compute such terms
10
+ once per rollout:
11
+
12
+ * a :class:`RolloutCache` that is *active only inside* a patched ``SampleDiffusion._sample_rollout``
13
+ (inference, ``torch.no_grad``), so training, activation checkpointing and any other use of the
14
+ layers is untouched;
15
+ * a registry of tensors known to be static (matched by object identity *and* ``_version`` so
16
+ in-place edits invalidate), and a byte budget so that very large inputs degrade gracefully
17
+ (entries that do not fit are simply recomputed, exactly as upstream does).
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import contextlib
23
+ import contextvars
24
+ import os
25
+ from collections.abc import Callable, Iterator
26
+ from typing import Any
27
+
28
+ import torch
29
+ from torch import Tensor
30
+
31
+ _ACTIVE: contextvars.ContextVar[RolloutCache | None] = contextvars.ContextVar(
32
+ "openfold3_accel_rollout_cache", default=None
33
+ )
34
+
35
+ #: Fraction of *available* RAM the cache may use when no explicit budget is configured.
36
+ _RAM_FRACTION = 0.25
37
+ _MAX_DEFAULT_BYTES = 8 * 2**30
38
+
39
+
40
+ def _available_ram_bytes() -> int | None:
41
+ try:
42
+ with open("/proc/meminfo") as fh:
43
+ for line in fh:
44
+ if line.startswith("MemAvailable:"):
45
+ return int(line.split()[1]) * 1024
46
+ except OSError:
47
+ pass
48
+ try:
49
+ return os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_AVPHYS_PAGES")
50
+ except (ValueError, OSError, AttributeError):
51
+ return None
52
+
53
+
54
+ def default_budget_bytes() -> int:
55
+ """Cache budget: ``OPENFOLD3_ACCEL_CACHE_MB`` if set, else 25% of available RAM (max 8 GiB)."""
56
+ env = os.environ.get("OPENFOLD3_ACCEL_CACHE_MB")
57
+ if env:
58
+ try:
59
+ return max(0, int(float(env) * 2**20))
60
+ except ValueError:
61
+ pass
62
+ avail = _available_ram_bytes()
63
+ if avail is None:
64
+ return 2 * 2**30
65
+ return int(min(_MAX_DEFAULT_BYTES, avail * _RAM_FRACTION))
66
+
67
+
68
+ def _nbytes(value: Any) -> int:
69
+ if isinstance(value, Tensor):
70
+ return value.numel() * value.element_size()
71
+ if isinstance(value, tuple | list):
72
+ return sum(_nbytes(v) for v in value)
73
+ return 0
74
+
75
+
76
+ def _tensors(value: Any) -> Iterator[Tensor]:
77
+ if isinstance(value, Tensor):
78
+ yield value
79
+ elif isinstance(value, tuple | list):
80
+ for v in value:
81
+ yield from _tensors(v)
82
+
83
+
84
+ def _ver(t: Tensor) -> int:
85
+ """Version counter of ``t``; -1 for inference tensors, which do not track one.
86
+
87
+ Inference tensors (created under ``torch.inference_mode()``, e.g. by Lightning's ``Trainer.predict``)
88
+ raise on ``_version``. They cannot be modified outside inference mode, and OpenFold3 never mutates
89
+ the rollout's conditioning tensors in place, so identity alone is used for them.
90
+ """
91
+ try:
92
+ return t._version
93
+ except RuntimeError:
94
+ return -1
95
+
96
+
97
+ class RolloutCache:
98
+ """Per-rollout memo table. Not thread-safe by design: one cache lives in one context."""
99
+
100
+ def __init__(self, budget_bytes: int | None = None):
101
+ self.budget = default_budget_bytes() if budget_bytes is None else budget_bytes
102
+ self.used = 0
103
+ self.hits = 0
104
+ self.misses = 0
105
+ self.overflow = 0
106
+ self.by_key: dict[str, list[int]] = {}
107
+ self._static: dict[int, tuple[Tensor, int]] = {}
108
+ self._memo: dict[Any, Any] = {}
109
+
110
+ # -- static-tensor registry ---------------------------------------------------------------
111
+ def mark_static(self, *tensors: Tensor | None) -> None:
112
+ """Declare tensors constant for the lifetime of the rollout (strong refs are kept)."""
113
+ for t in tensors:
114
+ if isinstance(t, Tensor):
115
+ self._static[id(t)] = (t, _ver(t))
116
+
117
+ def is_static(self, t: Tensor | None) -> bool:
118
+ if not isinstance(t, Tensor):
119
+ return False
120
+ entry = self._static.get(id(t))
121
+ return entry is not None and entry[0] is t and entry[1] == _ver(t)
122
+
123
+ # -- memoisation ----------------------------------------------------------------------------
124
+ def memo(self, key: Any, compute: Callable[[], Any], *, mark: bool = True) -> Any:
125
+ """Return ``compute()``, computing it at most once per rollout (budget permitting).
126
+
127
+ Tensors in the result are registered as static so that downstream layers can memoise on
128
+ them too. When the budget is exhausted the value is returned uncached and *not*
129
+ registered, so everything derived from it is also recomputed - i.e. upstream behaviour.
130
+ """
131
+ name = str(key[0]) if isinstance(key, tuple) else str(key)
132
+ counts = self.by_key.setdefault(name, [0, 0])
133
+ if key in self._memo:
134
+ self.hits += 1
135
+ counts[0] += 1
136
+ return self._memo[key]
137
+ self.misses += 1
138
+ counts[1] += 1
139
+ value = compute()
140
+ nb = _nbytes(value)
141
+ if self.used + nb > self.budget:
142
+ self.overflow += 1
143
+ return value
144
+ self.used += nb
145
+ self._memo[key] = value
146
+ if mark:
147
+ self.mark_static(*_tensors(value))
148
+ return value
149
+
150
+ def stats(self) -> dict:
151
+ return dict(
152
+ by_key={k: tuple(v) for k, v in self.by_key.items()},
153
+ hits=self.hits,
154
+ misses=self.misses,
155
+ overflow=self.overflow,
156
+ used_bytes=self.used,
157
+ budget_bytes=self.budget,
158
+ )
159
+
160
+
161
+ def _exporting() -> bool:
162
+ """True while tracing / exporting / compiling (ONNX, TorchScript, ``torch.export``, ``torch.compile``).
163
+
164
+ Identity-keyed memoisation is meaningless inside a trace, so upstream code runs instead.
165
+ """
166
+ try:
167
+ if torch.onnx.is_in_onnx_export() or torch.jit.is_tracing():
168
+ return True
169
+ except Exception: # noqa: BLE001
170
+ pass
171
+ for name in ("is_exporting", "is_compiling"):
172
+ f = getattr(torch.compiler, name, None)
173
+ try:
174
+ if f is not None and f():
175
+ return True
176
+ except Exception: # noqa: BLE001
177
+ pass
178
+ return False
179
+
180
+
181
+ def active() -> RolloutCache | None:
182
+ """The cache of the rollout currently executing in this context, if any (and only at inference)."""
183
+ c = _ACTIVE.get()
184
+ if c is None or torch.is_grad_enabled() or _exporting():
185
+ return None
186
+ return c
187
+
188
+
189
+ @contextlib.contextmanager
190
+ def rollout_scope(budget_bytes: int | None = None) -> Iterator[RolloutCache]:
191
+ """Activate a fresh :class:`RolloutCache`; it is dropped (freeing its memory) on exit."""
192
+ cache = RolloutCache(budget_bytes)
193
+ token = _ACTIVE.set(cache)
194
+ try:
195
+ yield cache
196
+ finally:
197
+ _ACTIVE.reset(token)
198
+ LAST_STATS.update(cache.stats())
199
+
200
+
201
+ #: Statistics of the most recently completed rollout (for diagnostics / benchmarks).
202
+ LAST_STATS: dict[str, int] = {}
@@ -0,0 +1,84 @@
1
+ """Version gating and source fingerprints for patch targets.
2
+
3
+ OpenFold3's internals are private and change between releases. Instead of trusting a version range
4
+ alone, every patch is applied only if
5
+
6
+ * the installed ``openfold3`` is inside the tested range, **and**
7
+ * the whitespace-normalised source of the exact function being replaced matches a fingerprint that
8
+ the replacement has been verified against.
9
+
10
+ Anything else is left untouched (the original OpenFold3 code runs) and is reported by
11
+ :func:`openfold3_accel.status`. Regenerate the table for new releases with
12
+ ``python scripts/fingerprint_versions.py`` after reading the upstream diff of each target.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import hashlib
18
+ import inspect
19
+ import re
20
+ from importlib import metadata
21
+
22
+ #: Inclusive lower / exclusive upper bound of OpenFold3 releases this package is tested with.
23
+ MIN_OPENFOLD3 = (0, 5, 0)
24
+ MAX_OPENFOLD3_EXCLUSIVE = (0, 6, 0)
25
+
26
+ #: Known-good source fingerprints per patch target (see ``scripts/fingerprint_versions.py``).
27
+ #: ``dev`` fingerprints are those of the commit pinned in ``OPENFOLD3_COMMIT``.
28
+ FINGERPRINTS: dict[str, frozenset[str]] = { # openfold3 0.5.0 and 0.5.1 (identical)
29
+ "SampleDiffusion._sample_rollout": frozenset({"8bd6b31fdcda"}),
30
+ "DiffusionConditioning.forward": frozenset({"f087b75e4de9"}),
31
+ "DiffusionTransformer.forward": frozenset({"595d4303fea0"}),
32
+ "DiffusionAttentionPairBias._prep_bias": frozenset({"bdc267d1d3cf"}),
33
+ "AdaLN.forward": frozenset({"7757a8da48bc"}),
34
+ "ConditionedTransitionBlock._transition": frozenset({"ad932f303448"}),
35
+ "AtomAttentionEncoder.get_atom_reps": frozenset({"6fea8030df81"}),
36
+ "CrossAttentionPairBias.forward": frozenset({"0f7d5d1d435d"}),
37
+ "SampleDiffusion._sample_rollout[bf16]": frozenset({"8bd6b31fdcda"}),
38
+ "DiffusionModule.forward": frozenset({"8f7737923ccd"}),
39
+ "attention._attention": frozenset({"bfffc382fcae"}),
40
+ "initialization.trunc_normal_init_": frozenset({"a7a22ae83444"}),
41
+ }
42
+
43
+
44
+ def fingerprint(fn) -> str | None:
45
+ """Whitespace-insensitive SHA-256 prefix of ``fn``'s source, or ``None`` if unavailable."""
46
+ try:
47
+ src = inspect.getsource(fn)
48
+ except (OSError, TypeError):
49
+ return None
50
+ return fingerprint_source(src)
51
+
52
+
53
+ def fingerprint_source(src: str) -> str:
54
+ return hashlib.sha256(re.sub(r"\s+", "", src).encode()).hexdigest()[:12]
55
+
56
+
57
+ def parse_version(v: str) -> tuple[int, ...]:
58
+ parts = []
59
+ for tok in re.split(r"[.+\-]", v):
60
+ m = re.match(r"\d+", tok)
61
+ if not m:
62
+ break
63
+ parts.append(int(m.group()))
64
+ return tuple(parts)
65
+
66
+
67
+ def openfold3_version() -> str | None:
68
+ try:
69
+ return metadata.version("openfold3")
70
+ except metadata.PackageNotFoundError:
71
+ return None
72
+
73
+
74
+ def version_supported(v: str | None) -> tuple[bool, str]:
75
+ if v is None:
76
+ return False, "openfold3 is not installed"
77
+ t = parse_version(v)
78
+ if not t:
79
+ return False, f"unparseable openfold3 version {v!r}"
80
+ if t < MIN_OPENFOLD3 or t >= MAX_OPENFOLD3_EXCLUSIVE:
81
+ lo = ".".join(map(str, MIN_OPENFOLD3))
82
+ hi = ".".join(map(str, MAX_OPENFOLD3_EXCLUSIVE))
83
+ return False, f"openfold3 {v} is outside the tested range [{lo}, {hi})"
84
+ return True, "ok"