pymbar4 (#268)

* fix #207 
* switch from pymbar 3 to pymbar 4 (minimal requirement pymbar>=4)
* remove deprecated AutoMBAR
* change estimators.MBAR kwarg method from "hybr" to "robust"
* docs: note pymbar 4.x for 2.0
* update tests
* Update CHANGES

Co-authored-by: Oliver Beckstein <orbeckst@gmail.com>

Author: xiki-tempula

CHANGES

@@ -13,15 +13,24 @@ The rules for this file:
   * release numbers follow "Semantic Versioning" https://semver.org
 
 ------------------------------------------------------------------------------
-
 */*/* xiki-tempula, orbeckst
 
   * 2.0.0
 
+Changes
+  - use pymbar 4 as backend; this release is incompatible with
+    pymbar 3.x (issue #207, PR #268, discussion #205).
+  - The default for keyword argument `method` in estimators.MBAR was changed
+    from "hybr" to "robust" (issue #207, PR #268).
+
 Enhancements
-  - Add a new Error when no file has been matched in workflow.ABFE (PR #289).
+  - Raise ValueError when no file has been matched in workflow.ABFE (PR #289).
   - In workflows, the output folder will be created if it did not exist before
     (PR #290).
+  
+Removals
+  - The AutoMBAR estimator was removed because pymbar 4's MBAR contains
+    equivalent functionality. (issue #284)
 
 
 12/09/2022 DrDomenicoMarson, xiki-tempula, orbeckst

devtools/conda-envs/test_env.yaml

@@ -5,7 +5,7 @@ dependencies:
 - python
 - numpy
 - pandas
-- pymbar >=3.0.5,<4
+- pymbar>=4
 - scipy
 - scikit-learn
 - matplotlib

docs/index.rst

@@ -14,11 +14,11 @@ These functions are simple in usage and pure in scope, and can be chained togeth
 
 **alchemlyb** seeks to be as boring and simple as possible to enable more complex work. Its components allow work at all scales, from use on small systems using a single workstation to larger datasets that require distributed computing using libraries such as `dask`_.
 
-The library is *under active development*. However, it is used by multiple groups in a production environment. We use `semantic versioning`_ to indicate clearly what kind of changes you may expect between releases. With release 1.0.0, the API has stabilized and is guaranteed to remain backwards-compatible until a 2.0.0 release.
+The library is *under active development*. However, it is used by multiple groups in a production environment. We use `semantic versioning`_ to indicate clearly what kind of changes you may expect between releases. Within any major release (1.x, 2.x, ...), the API is stable and is guaranteed to remain backwards-compatible.
 
 .. Note::   
-   The current 1.x release of alchemlyb *only* supports `pymbar`_ releases **>= 3.0.5, <4.0**.
-   A future 2.x release of alchemlyb will *only* support pymbar **>= 4.0** (see `discussion #205`_ and `issue #207`_)
+   The **current 2.x release** of alchemlyb *only* supports `pymbar`_ releases **>= 4.0**.
+   (Previous 1.x releases only support pymbar >= 3.0.5, <4.) See `discussion #205`_ and `issue #207`_.
 
 See :ref:`contact` for how to get in touch if you have questions or find problems.
 

environment.yml

@@ -2,10 +2,10 @@ name: alchemlyb
 channels:
 - conda-forge
 dependencies:
-- python=3.8
+- python
 - numpy
 - pandas
-- pymbar >=3.0.5,<4
+- pymbar>=4
 - scipy
 - scikit-learn
 - matplotlib

setup.py

@@ -11,39 +11,46 @@
 
 import versioneer
 
-setup(name='alchemlyb',
-      version=versioneer.get_version(),
-      cmdclass=versioneer.get_cmdclass(),
-      description='the simple alchemistry library',
-      author='David Dotson',
-      author_email='dotsdl@gmail.com',
-      maintainer='Oliver Beckstein',
-      maintainer_email='orbeckst@gmail.com',
-      classifiers=[
-        'Development Status :: 5 - Production/Stable',
-        'Intended Audience :: Science/Research',
-        'License :: OSI Approved :: BSD License',
-        'Operating System :: POSIX',
-        'Operating System :: MacOS :: MacOS X',
-        'Operating System :: Microsoft :: Windows ',
-        'Programming Language :: Python',
-        'Programming Language :: Python :: 3',
-        'Programming Language :: Python :: 3.8',
-        'Programming Language :: Python :: 3.9',
-        'Programming Language :: Python :: 3.10',
-        'Programming Language :: Python :: 3.11',
-        'Topic :: Scientific/Engineering',
-        'Topic :: Scientific/Engineering :: Bio-Informatics',
-        'Topic :: Scientific/Engineering :: Chemistry',
-        'Topic :: Software Development :: Libraries :: Python Modules',
-        ],
-      packages=find_packages('src'),
-      package_dir={'': 'src'},
-      license='BSD',
-      long_description=open('README.rst').read(),
-      long_description_content_type='text/x-rst',
-      python_requires='>=3.8',
-      tests_require = ['pytest', 'alchemtest'],
-      install_requires=['numpy', 'pandas>=1.4', 'pymbar>=3.0.5,<4',
-                        'scipy', 'scikit-learn', 'matplotlib']
-      )
+setup(
+    name="alchemlyb",
+    version=versioneer.get_version(),
+    cmdclass=versioneer.get_cmdclass(),
+    description="the simple alchemistry library",
+    author="David Dotson",
+    author_email="dotsdl@gmail.com",
+    maintainer="Oliver Beckstein",
+    maintainer_email="orbeckst@gmail.com",
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Science/Research",
+        "License :: OSI Approved :: BSD License",
+        "Operating System :: POSIX",
+        "Operating System :: MacOS :: MacOS X",
+        "Operating System :: Microsoft :: Windows ",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Topic :: Scientific/Engineering",
+        "Topic :: Scientific/Engineering :: Bio-Informatics",
+        "Topic :: Scientific/Engineering :: Chemistry",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+    packages=find_packages("src"),
+    package_dir={"": "src"},
+    license="BSD",
+    long_description=open("README.rst").read(),
+    long_description_content_type="text/x-rst",
+    python_requires=">=3.8",
+    tests_require=["pytest", "alchemtest"],
+    install_requires=[
+        "numpy",
+        "pandas>=1.4",
+        "pymbar>=4",
+        "scipy",
+        "scikit-learn",
+        "matplotlib",
+    ],
+)

src/alchemlyb/convergence/convergence.py

@@ -7,8 +7,7 @@
 import pandas as pd
 
 from .. import concat
-from ..estimators import AutoMBAR as MBAR
-from ..estimators import BAR, TI, FEP_ESTIMATORS, TI_ESTIMATORS
+from ..estimators import BAR, TI, MBAR, FEP_ESTIMATORS, TI_ESTIMATORS
 from ..postprocessors.units import to_kT
 
 estimators_dispatch = {"BAR": BAR, "TI": TI, "MBAR": MBAR}
@@ -57,19 +56,13 @@ def forward_backward_convergence(df_list, estimator="MBAR", num=10, **kwargs):
             9  3.044149       0.016405  3.044385        0.016402            1.0
 
 
-    Note
-    -----
-    :class:`~alchemlyb.estimators.AutoMBAR` is used when ``estimator='MBAR'``,
-    supply ``method`` keyword to restore the behavior of
-    :class:`~alchemlyb.estimators.MBAR`.
-    (:code:`forward_backward_convergence(u_nk, 'MBAR', num=2, method='adaptive')`)
-
-
     .. versionadded:: 0.6.0
     .. versionchanged:: 1.0.0
        The ``estimator`` accepts uppercase input.
        The default for using ``estimator='MBAR'`` was changed from
        :class:`~alchemlyb.estimators.MBAR` to :class:`~alchemlyb.estimators.AutoMBAR`.
+    .. versionchanged:: 2.0.0
+       Use pymbar.MBAR instead of the AutoMBAR option.
 
     """
     logger = logging.getLogger("alchemlyb.convergence." "forward_backward_convergence")

src/alchemlyb/estimators/__init__.py

@@ -1,6 +1,6 @@
 from .bar_ import BAR
-from .mbar_ import MBAR, AutoMBAR
+from .mbar_ import MBAR
 from .ti_ import TI
 
-FEP_ESTIMATORS = [MBAR.__name__, AutoMBAR.__name__, BAR.__name__]
+FEP_ESTIMATORS = [MBAR.__name__, BAR.__name__]
 TI_ESTIMATORS = [TI.__name__]

src/alchemlyb/estimators/bar_.py

@@ -1,6 +1,6 @@
 import numpy as np
 import pandas as pd
-from pymbar import BAR as BAR_
+from pymbar.other_estimators import bar as BAR_
 from sklearn.base import BaseEstimator
 
 from .base import _EstimatorMixOut
@@ -113,7 +113,7 @@ def fit(self, u_nk):
             w_r = uk1.iloc[:, k] - uk1.iloc[:, k + 1]
 
             # now determine df and ddf using pymbar.BAR
-            df, ddf = BAR_(
+            out = BAR_(
                 w_f,
                 w_r,
                 method=self.method,
@@ -122,6 +122,7 @@ def fit(self, u_nk):
                 verbose=self.verbose,
             )
 
+            df, ddf = out["Delta_f"], out["dDelta_f"]
             deltas = np.append(deltas, df)
             d_deltas = np.append(d_deltas, ddf**2)