Update changelog

.github/workflows/ci.yaml

@@ -36,7 +36,7 @@ jobs:
         - os: macOS-latest
           python-version: 3.10
         - os: macOS-latest
-          python-version: 3.11
+          python-version: 3.11        
         - os: windows-latest
           python-version: 3.10
         - os: windows-latest
@@ -50,7 +50,7 @@ jobs:
       with:
         environment-file: devtools/conda-envs/test_env.yaml
         environment-name: test
-        extra-specs: |
+        create-args: |
             python=${{ matrix.python-version }}
 
     - name: Install package (with no dependencies)
@@ -64,7 +64,7 @@ jobs:
         MPLBACKEND: agg
 
     - name: Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
         name: codecov-${{ matrix.os }}-py${{ matrix.python-version }}

CHANGES

@@ -14,15 +14,42 @@ The rules for this file:
 
 ------------------------------------------------------------------------------
 
-*/*/2023 hl2500, xiki-tempula, jaclark5
+08/07/2024 orbeckst, xiki-tempula, jaclark5
+
+  * 2.3.1
+
+Changes:
+  - alchemlyb adopts SPEC 0 (replaces NEP 29)
+    https://scientific-python.org/specs/spec-0000/
+  - Add support for LAMMPS FEP files (Issue #349, PR #348)
+
+Fixes
+  - Support matplotlib 3.9.0 (issue alchemistry/flamel#28, PR#319).
+
+
+21/05/2024 xiki-tempula
+
+  * 2.3.0
+
+Changes
+  - Default value for keyword argument `initial_nk` of the MBAR estimator was
+    changed to "BAR" (run an initial BAR calculation before MBAR) instead of 
+    `None` (start from all zeros) as this change provides a sizable speedup (PR #357)
+
+Enhancements
+  - `forward_backward_convergence` uses the bootstrap error when the statistical error
+    is too large. (PR #358)
+  - `BAR` result is used as initial guess for `MBAR` estimator. (PR #357)
+  - `forward_backward_convergence` uses the result from the previous step as the initial guess for the next step. (PR #357)
+
+06/04/2024 hl2500, xiki-tempula
 
   * 2.2.0
 
 Changes
   - Require pandas >= 2.1 (PR #340)
   - For pandas>=2.1, metadata will be loaded from the parquet file (issue #331, PR #340).
   - add support for Python 3.12, remove Python 3.8 support (issue #341, PR #304).
-  - Add support for LAMMPS FEP files (Issue #349, PR #348)
 
 Enhancements
   - Add a TI estimator using gaussian quadrature to calculate the free energy.
@@ -31,6 +58,10 @@ Enhancements
     (issue #337, PR #338)
   - ValueError issued when `df` and `series` for `statistical_inefficiency`
     doesn't have the same length (issue #337, PR #338)
+
+Fixes
+  - data_fraction column in workflow.convergence won't be affected by the
+    unit conversion (issue #350, PR#319).
 
 
 22/06/2023 xiki-tempula

MANIFEST.in

@@ -1,6 +1,6 @@
 include *.rst
 recursive-include src/alchemlyb *.gz *.bz2 *.zip *.rst *.txt
-include README.rst
+include README.md
 include LICENSE
 include versioneer.py
 include src/alchemlyb/_version.py

README.md

@@ -0,0 +1,54 @@
+# alchemlyb: the simple alchemistry library
+
+[![Zenodo DOI](https://zenodo.org/badge/68669096.svg)](https://zenodo.org/badge/latestdoi/68669096) [![Documentation](https://readthedocs.org/projects/alchemlyb/badge/?version=latest)](http://alchemlyb.readthedocs.io/en/latest/) [![Build Status](https://github.com/alchemistry/alchemlyb/actions/workflows/ci.yaml/badge.svg?branch=master)](https://github.com/alchemistry/alchemlyb/actions/workflows/ci.yaml) [![Code coverage](https://codecov.io/gh/alchemistry/alchemlyb/branch/master/graph/badge.svg)](https://codecov.io/gh/alchemistry/alchemlyb) [![anaconda package](https://anaconda.org/conda-forge/alchemlyb/badges/version.svg)](https://anaconda.org/conda-forge/alchemlyb)
+
+**alchemlyb** makes alchemical free energy calculations easier to do by leveraging the full power and flexibility of the PyData stack. It includes:
+
+1. Parsers for extracting raw data from output files of common molecular dynamics engines such as [GROMACS](http://www.gromacs.org/), [AMBER](http://ambermd.org/), [NAMD](http://www.ks.uiuc.edu/Research/namd/) and [other simulation codes](https://alchemlyb.readthedocs.io/en/latest/parsing.html).
+
+2. Subsamplers for obtaining uncorrelated samples from timeseries data (including extracting independent, equilibrated samples [Chodera2016](#chodera2016) as implemented in the [pymbar](http://pymbar.readthedocs.io/) package).
+
+3. Estimators for obtaining free energies directly from this data, using best-practices approaches for multistate Bennett acceptance ratio (MBAR) [Shirts2008](#shirts2008) and BAR (from [pymbar](http://pymbar.readthedocs.io/)) and thermodynamic integration (TI).
+
+## Installation
+
+**Install** via `pip` from [PyPi (alchemlyb)](https://pypi.org/project/alchemlyb):
+
+```bash
+pip install alchemlyb
+```
+
+or as a `conda` package from the [conda-forge (alchemlyb)](https://anaconda.org/conda-forge/alchemlyb) channel:
+
+```bash
+conda install -c conda-forge alchemlyb
+```
+
+**Update** with `pip`:
+
+```bash
+pip install --update alchemlyb
+```
+
+or with `conda` run:
+
+```bash
+conda update -c conda-forge alchemlyb
+```
+
+to get the latest released version.
+
+## Getting involved
+
+Contributions of all kinds are very welcome.
+
+If you have questions or want to discuss alchemlyb please post in the [alchemlyb Discussions](https://github.com/alchemistry/alchemlyb/discussions).
+
+If you have bug reports or feature requests then please get in touch with us through the [Issue Tracker](https://github.com/alchemistry/alchemlyb/issues).
+
+We also welcome code contributions: have a look at our [Developer Guide](https://github.com/alchemistry/alchemlyb/wiki/Developer-Guide). Open an issue with the proposed fix or change in the [Issue Tracker](https://github.com/alchemistry/alchemlyb/issues) and submit a pull request against the [alchemistry/alchemlyb](https://github.com/alchemistry/alchemlyb) GitHub repository.
+
+## References
+
+- <a name="shirts2008"></a> Shirts, M.R., and Chodera, J.D. (2008). Statistically optimal analysis of samples from multiple equilibrium states. The Journal of Chemical Physics 129, 124105.
+- <a name="chodera2016"></a> Chodera, J.D. (2016). A Simple Method for Automated Equilibration Detection in Molecular Simulations. Journal of Chemical Theory and Computation 12, 1799–1805.

devtools/conda-envs/test_env.yaml

@@ -8,7 +8,7 @@ dependencies:
 - pymbar>=4
 - scipy
 - scikit-learn
-- matplotlib
+- matplotlib>=3.7
 - loguru
 - pyarrow
 

docs/estimators-fep.rst

@@ -34,7 +34,13 @@ The :meth:`~alchemlyb.estimators.MBAR.fit` method is used to perform the free en
     >>> mbar_vdw = MBAR().fit(u_nk_vdw)
 
 The sum of the endpoint free energy differences will be the free energy of solvation for benzene in water.
-The free energy differences (in units of :math:`k_B T`) between each :math:`\lambda` window can be accessed via the ``delta_f_`` attribute::
+The free energy differences (in units of :math:`k_B T`) between each :math:`\lambda` window can be accessed via the ``delta_f_`` attribute.
+
+The elements of the resulting matrix ``delta_f_`` represent the free energy differences between different lambda windows. Specifically, ``delta_f_[i, j]`` represents the free energy difference between lambda window ``j`` and lambda window ``i``. This matrix can be utilized to obtain the desired free energy differences for various states.
+
+For instance, to obtain the free energy difference between the lambda values of 0 and 1, you can directly access ``delta_f_.loc[0.00, 1.00]``.
+
+Additionally, the errors on these differences are accessible via the ``d_delta_f_`` attribute.
 
     >>> mbar_coul.delta_f_
               0.00      0.25      0.50      0.75      1.00

docs/index.rst

@@ -52,14 +52,12 @@ Development is done in the open on `GitHub`_.
 Software engineering best-practices are used throughout, including continuous integration testing via Github Actions, up-to-date documentation, and regular releases.
 
 .. Note::
-   With release 0.5.0, the alchemlyb project adopted `NEP 29`_ to determine which versions of Python and NumPy_ will be supported.
-   When we release a new major or minor version, alchemlyb will support *at least all minor versions of Python introduced and released in the prior 42 months from the release date with a minimum of 2 minor versions of Python*, and *all minor versions of NumPy released in the prior 24 months from the anticipated release date with a minimum of 3 minor versions of NumPy*.
-
-The pandas_ package (one of our other primary dependencies) also follows `NEP 29`_ so this support policy will make it easier to maintain **alchemlyb** in the future.
+   The alchemlyb project uses `SPEC 0`_ to determine which versions of  Python, NumPy_, and pandas_  will be supported.
+   When we release a new major or minor version, alchemlyb will support *at least all minor versions of Python introduced and released in the prior 3 years from the release date*, and *all minor versions of NumPy and pandas released in the prior 2 years from the anticipated release date*.
 
 
 .. _`GitHub`: https://github.com/alchemistry/alchemlyb
-.. _`NEP 29`: https://numpy.org/neps/nep-0029-deprecation_policy.html
+.. _`SPEC 0`: https://scientific-python.org/specs/spec-0000/
 .. _NumPy: https://numpy.org
 .. _pandas: https://pandas.pydata.org/
 

docs/requirements.yaml

@@ -0,0 +1,9 @@
+name: docs
+channels:
+dependencies:
+    # Base depends
+  - python=3.10
+  - pip
+  # Doc
+  - sphinx
+  - sphinx_rtd_theme

docs/workflows/alchemlyb.workflows.base.rst

@@ -7,15 +7,15 @@ basic API template for the workflow development.  The workflow should
 be able to run in an automatic fashion. ::
 
     >>> from alchemlyb.workflows.base import WorkflowBase
-    >>> workflow = WorkflowBase(units='kT', software='Gromacs', T=298,
+    >>> workflow = WorkflowBase(units='kT', software='GROMACS', T=298,
         out='./', *args, **kwargs)
     >>> workflow.run(*args, **kwargs)
 
 Three main functions are provided such that the workflow could be run in a
 step-by-step fashion. ::
 
     >>> from alchemlyb.workflows.base import WorkflowBase
-    >>> workflow = WorkflowBase(units='kT', software='Gromacs', T=298,
+    >>> workflow = WorkflowBase(units='kT', software='GROMACS', T=298,
         out='./', *args, **kwargs)
     >>> workflow.read(*args, **kwargs)
     >>> workflow.preprocess(*args, **kwargs)

environment.yml

@@ -9,5 +9,5 @@ dependencies:
 - scipy
 - scikit-learn
 - pyarrow
-- matplotlib
+- matplotlib>=3.7
 - loguru

readthedocs.yml

@@ -13,7 +13,7 @@ build:
     python: "mambaforge-4.10"
 
 conda:
-    environment: devtools/conda-envs/test_env.yaml
+    environment: docs/requirements.yaml
 
 python:
   install:

setup.py

@@ -41,8 +41,8 @@
     packages=find_packages("src"),
     package_dir={"": "src"},
     license="BSD",
-    long_description=open("README.rst").read(),
-    long_description_content_type="text/x-rst",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
     python_requires=">=3.9",
     tests_require=["pytest", "alchemtest"],
     install_requires=[
@@ -51,7 +51,7 @@
         "pymbar>=4",
         "scipy",
         "scikit-learn",
-        "matplotlib",
+        "matplotlib>=3.7",
         "loguru",
         "pyarrow",
     ],