openmm-opes 0.1.0__tar.gz

openmm_opes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charlles Abreu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openmm_opes-0.1.0/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: openmm-opes
+Version: 0.1.0
+Summary: OpenMM implementation of On-the-fly Probability Enhanced Sampling (OPES)
+Author: Charlles Abreu
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: openmm>=8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: ruff>=0.16; extra == "dev"
+Requires-Dist: ty==0.0.72; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24; extra == "docs"
+Dynamic: license-file
+
+# openmm-opes
+
+[![CI](https://github.com/craabreu/openmm-opes/actions/workflows/ci.yml/badge.svg)](https://github.com/craabreu/openmm-opes/actions/workflows/ci.yml)
+
+An [OpenMM](https://openmm.org) implementation of On-the-fly Probability
+Enhanced Sampling (OPES) and OPES-explore.
+
+## Installation
+
+```bash
+pip install openmm-opes
+```
+
+## Usage
+
+```python
+from openmm_opes import OPES
+
+sampler = OPES(system, variables, temperature, barrier, frequency=500,
+               varianceFrequency=50)
+sampler.step(simulation, 1_000_000)
+fes = sampler.getFreeEnergy()
+```
+
+Full documentation: <https://craabreu.github.io/openmm-opes>
+
+## Origin
+
+This library packages and hardens the prototype implementation developed in
+[craabreu/opes-simulations](https://github.com/craabreu/opes-simulations),
+porting its `OPES`/`OnlineKDE` classes into a tested, documented package.
+
+## References
+
+- Invernizzi & Parrinello, J. Phys. Chem. Lett. 2020,
+  [doi:10.1021/acs.jpclett.0c00497](https://doi.org/10.1021/acs.jpclett.0c00497)
+- Invernizzi & Parrinello, J. Chem. Theory Comput. 2022,
+  [doi:10.1021/acs.jctc.2c00152](https://doi.org/10.1021/acs.jctc.2c00152)
+
+## License
+
+MIT

openmm_opes-0.1.0/README.md

@@ -0,0 +1,42 @@
+# openmm-opes
+
+[![CI](https://github.com/craabreu/openmm-opes/actions/workflows/ci.yml/badge.svg)](https://github.com/craabreu/openmm-opes/actions/workflows/ci.yml)
+
+An [OpenMM](https://openmm.org) implementation of On-the-fly Probability
+Enhanced Sampling (OPES) and OPES-explore.
+
+## Installation
+
+```bash
+pip install openmm-opes
+```
+
+## Usage
+
+```python
+from openmm_opes import OPES
+
+sampler = OPES(system, variables, temperature, barrier, frequency=500,
+               varianceFrequency=50)
+sampler.step(simulation, 1_000_000)
+fes = sampler.getFreeEnergy()
+```
+
+Full documentation: <https://craabreu.github.io/openmm-opes>
+
+## Origin
+
+This library packages and hardens the prototype implementation developed in
+[craabreu/opes-simulations](https://github.com/craabreu/opes-simulations),
+porting its `OPES`/`OnlineKDE` classes into a tested, documented package.
+
+## References
+
+- Invernizzi & Parrinello, J. Phys. Chem. Lett. 2020,
+  [doi:10.1021/acs.jpclett.0c00497](https://doi.org/10.1021/acs.jpclett.0c00497)
+- Invernizzi & Parrinello, J. Chem. Theory Comput. 2022,
+  [doi:10.1021/acs.jctc.2c00152](https://doi.org/10.1021/acs.jctc.2c00152)
+
+## License
+
+MIT

openmm_opes-0.1.0/pyproject.toml

@@ -0,0 +1,91 @@
+[project]
+name = "openmm-opes"
+version = "0.1.0"
+description = "OpenMM implementation of On-the-fly Probability Enhanced Sampling (OPES)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Charlles Abreu" }]
+requires-python = ">=3.11"
+dependencies = ["numpy>=1.24", "scipy>=1.10", "openmm>=8.1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4", "ruff>=0.16", "ty==0.0.72"]
+# mkdocs >= 1.6 is required for the exclude_docs setting used by mkdocs.yml
+docs = ["mkdocs>=1.6", "mkdocs-material>=9.5", "mkdocstrings[python]>=0.24"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["slow: end-to-end simulations that take minutes"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+include = ["src/**/*.py", "tests/**/*.py"]
+
+[tool.ruff.lint]
+# Deliberately no "N" rules: the public API is camelCase to match OpenMM.
+select = ["E", "F", "I", "UP", "B", "C4", "RUF"]
+
+[tool.ty.analysis]
+# OpenMM ships no type stubs, so the lint job never installs it: doing so
+# would still leave every attribute access untyped, for no benefit.
+# online_kde is the ORIGINAL implementation, sys.path-shimmed at runtime from
+# a sibling repo (tests/data/make_reference.py) rather than installed, so it
+# is never resolvable statically.
+allowed-unresolved-imports = ["openmm", "openmm.**", "online_kde"]
+
+[[tool.ty.overrides]]
+# numpy-stubs gap, confirmed a false positive: np.logaddexp.reduce(array) is
+# ordinary numpy usage that runs correctly (see the passing test suite), but
+# the stub's reduce() overloads for binary ufuncs cannot be satisfied without
+# an explicit out= argument, so ty reports every plain reduce() call here as
+# having no matching overload.
+include = ["src/openmm_opes/kde.py", "tests/test_kde.py"]
+
+[tool.ty.overrides.rules]
+no-matching-overload = "ignore"
+
+[[tool.ty.overrides]]
+# numpy-stubs gap, confirmed a false positive: np.savez(path, **arrays) passes
+# arbitrary ndarrays through **kwds, but the stub resolves that against
+# allow_pickle: bool instead of **kwds: ArrayLike, reporting every array
+# argument as "expected bool". Same class of gap sieve's own pyproject.toml
+# documents for the identical call shape.
+include = ["tests/data/make_reference.py"]
+
+[tool.ty.overrides.rules]
+invalid-argument-type = "ignore"
+
+[[tool.ty.overrides]]
+# openmm.unit stub gap, confirmed a false positive: unit.kelvin and
+# unit.kilojoules_per_mole resolve fine, but unit.picosecond/picoseconds do
+# not, even though `dir(unit)` and runtime multiplication both confirm they
+# exist -- these unit constants are evidently built at import time in a way
+# ty's static analysis can't trace, unlike the ones assigned as literal
+# module-level names.
+include = ["tests/test_opes.py", "tests/test_integration.py"]
+
+[tool.ty.overrides.rules]
+unresolved-attribute = "ignore"
+unsupported-operator = "ignore"
+
+[[tool.ty.overrides]]
+# numpy-stubs gap, confirmed a false positive: ndarray.min() with no arguments
+# on an ordinary float64 array (e.g. analytic[mask].min() where analytic is
+# built as BARRIER_HEIGHT * (1 - grid**2) ** 2) runs correctly and returns a
+# float64 -- ty's own diagnostic even reports the array's dtype correctly as
+# float64 -- yet resolution picks the unrelated NDArray[object_] overload
+# instead of a float64-compatible one. Reproduced in isolation outside this
+# file, so this is a stub resolution gap, not anything about this code.
+include = ["tests/test_integration.py"]
+
+[tool.ty.overrides.rules]
+invalid-argument-type = "ignore"

openmm_opes-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openmm_opes-0.1.0/src/openmm_opes/__init__.py

@@ -0,0 +1,19 @@
+"""OpenMM implementation of On-the-fly Probability Enhanced Sampling (OPES)."""
+
+__version__ = "0.1.0"
+
+__all__ = ["OPES", "__version__"]
+
+
+def __getattr__(name):
+    """Import OPES lazily (PEP 562).
+
+    An eager ``from .opes import OPES`` would also run on
+    ``import openmm_opes.kde``, dragging openmm in and breaking the guarantee
+    that kde and io stay OpenMM-free. Task 1's test enforces that.
+    """
+    if name == "OPES":
+        from .opes import OPES
+
+        return OPES
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

openmm_opes-0.1.0/src/openmm_opes/io.py

@@ -0,0 +1,102 @@
+"""Multi-walker bias sharing through a shared directory.
+
+Pure NumPy. This module must not import openmm, and deliberately knows
+nothing about kernels: it moves flat dicts of arrays so it stays testable
+without a simulation.
+
+The format is ``np.savez``, not pickle. A walker reads files written by other
+processes out of a shared directory, and ``pickle.load`` on data from another
+process would be a remote-code-execution primitive. OpenMM's own Metadynamics
+writes .npy for the same reason.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import warnings
+
+import numpy as np
+
+FILENAME_PATTERN = re.compile(r"kde_(\d+)_(\d+)\.npz")
+
+
+class _LoadedBias:
+    """A peer's most recently seen state. Mirrors Metadynamics' own namedtuple."""
+
+    __slots__ = ("index", "state", "walkerId")
+
+    def __init__(self, walkerId: int, index: int, state: dict):
+        self.walkerId = walkerId
+        self.index = index
+        self.state = state
+
+
+class BiasSharer:
+    """Reads and writes walker bias states in a shared directory.
+
+    Parameters
+    ----------
+    biasDir
+        Directory shared by every walker.
+    walkerId
+        This walker's identifier. Drawn at random when omitted, from a fresh
+        generator so the global NumPy random state is left undisturbed.
+    """
+
+    def __init__(self, biasDir: str, walkerId: int | None = None):
+        self.biasDir = biasDir
+        self.walkerId = (
+            int(np.random.default_rng().integers(0x7FFFFFFF))
+            if walkerId is None
+            else walkerId
+        )
+        self._saveIndex = 0
+        self._loaded: dict[int, _LoadedBias] = {}
+
+    def _path(self, prefix: str, index: int) -> str:
+        return os.path.join(self.biasDir, f"{prefix}_{self.walkerId}_{index}.npz")
+
+    def save(self, state: dict) -> None:
+        """Write this walker's state atomically and drop the previous index."""
+        oldName = self._path("kde", self._saveIndex)
+        self._saveIndex += 1
+        tempName = self._path("temp", self._saveIndex)
+        fileName = self._path("kde", self._saveIndex)
+        np.savez(tempName, **state)
+        os.rename(tempName, fileName)
+        if os.path.exists(oldName):
+            os.remove(oldName)
+
+    def load(self) -> dict[int, dict]:
+        """Return peer states that are new or have advanced since the last call."""
+        updated: dict[int, dict] = {}
+        for filename in os.listdir(self.biasDir):
+            match = FILENAME_PATTERN.match(filename)
+            if match is None:
+                continue
+            walkerId, index = int(match.group(1)), int(match.group(2))
+            if walkerId == self.walkerId:
+                continue
+            known = self._loaded.get(walkerId)
+            if known is not None and index <= known.index:
+                continue
+            try:
+                with np.load(
+                    os.path.join(self.biasDir, filename), allow_pickle=False
+                ) as data:
+                    state = {key: data[key] for key in data.files}
+            except (OSError, ValueError):
+                warnings.warn(
+                    f"The file {filename} seems to have been deleted. Using the "
+                    "latest loaded data from the same walker.",
+                    stacklevel=2,
+                )
+                continue
+            self._loaded[walkerId] = _LoadedBias(walkerId, index, state)
+            updated[walkerId] = state
+        return updated
+
+    def getLoadedStates(self) -> dict[int, dict]:
+        """Every peer state seen so far, whether or not it changed recently."""
+        return {walkerId: bias.state for walkerId, bias in self._loaded.items()}