diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index d80f06dd..5a5f10e1 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -22,7 +22,7 @@ jobs: fail-fast: true matrix: os: ["ubuntu-latest", "macOS-latest", "windows-latest"] - python-version: ["3.7", "3.8", "3.9"] + python-version: ["3.7", "3.8", "3.9", "3.10"] steps: - uses: actions/checkout@v2 diff --git a/CHANGES b/CHANGES index 60d483c8..3c6c588d 100644 --- a/CHANGES +++ b/CHANGES @@ -13,13 +13,12 @@ The rules for this file: * release numbers follow "Semantic Versioning" https://semver.org ------------------------------------------------------------------------------ -??/??/2021 schlaicha, xiki-tempula, jhenin, ttjoseph, orbeckst +12/28/2021 schlaicha, xiki-tempula, jhenin, ttjoseph, orbeckst * 0.6.0 -Changes - Enhancements + - support Python 3.10 - support for Interleaved Double-Wide Sampling (IDWS) in NAMD (PR #135). Windows may be split across NAMD .fepout files, allowing for interrupted and restarted simulations, but each window must be complete (issue #145). diff --git a/README.rst b/README.rst index 51fca4b4..3ade4108 100644 --- a/README.rst +++ b/README.rst @@ -11,15 +11,41 @@ includes: molecular dynamics engines such as `GROMACS`_, `AMBER`_, `NAMD`_ and `other simulation codes`_. -2. Subsamplers for obtaining uncorrelated samples from timeseries data. +2. Subsamplers for obtaining uncorrelated samples from timeseries data + (including extracting independent, equilibrated samples + [Chodera2016]_ as implemented in the pymbar_ package). 3. Estimators for obtaining free energies directly from this data, using best-practices approaches for multistate Bennett acceptance ratio (MBAR) - [Shirts2008]_ and thermodynamic integration (TI). + [Shirts2008]_ and BAR (from pymbar_) and thermodynamic integration (TI). -In particular, it uses internally the excellent `pymbar -`_ library for performing MBAR and extracting -independent, equilibrated samples [Chodera2016]_. +.. _GROMACS: http://www.gromacs.org/ +.. _AMBER: http://ambermd.org/ +.. _NAMD: http://www.ks.uiuc.edu/Research/namd/ +.. _`other simulation codes`: https://alchemlyb.readthedocs.io/en/latest/parsing.html +.. _`pymbar`: http://pymbar.readthedocs.io/ + + +Getting involved +---------------- + +Contributions of all kinds are very welcome. + +If you have questions or want to discuss alchemlyb please post in the `alchemlyb Discussions`_. + +If you have bug reports or feature requests then please get in touch with us through the `Issue Tracker`_. + +We also welcome code contributions: have a look at our `Developer Guide`_. Open an issue with the proposed fix or change in the `Issue Tracker`_ and submit a pull request against the `alchemistry/alchemlyb`_ GitHub repository. + +.. _`alchemlyb Discussions`: https://github.com/alchemistry/alchemlyb/discussions +.. _`Developer Guide`: https://github.com/alchemistry/alchemlyb/wiki/Developer-Guide +.. _`Issue Tracker`: https://github.com/alchemistry/alchemlyb/issues +.. _`alchemistry/alchemlyb`: https://github.com/alchemistry/alchemlyb + + + +References +---------- .. [Shirts2008] Shirts, M.R., and Chodera, J.D. (2008). Statistically optimal analysis of samples from multiple equilibrium states. The Journal of Chemical @@ -29,14 +55,7 @@ independent, equilibrated samples [Chodera2016]_. Equilibration Detection in Molecular Simulations. Journal of Chemical Theory and Computation 12, 1799–1805. -.. _GROMACS: http://www.gromacs.org/ -.. _AMBER: http://ambermd.org/ - -.. _NAMD: http://www.ks.uiuc.edu/Research/namd/ - -.. _`other simulation codes`: https://alchemlyb.readthedocs.io/en/latest/parsing.html - .. |doi| image:: https://zenodo.org/badge/68669096.svg :alt: Zenodo DOI :scale: 100% diff --git a/docs/api_principles.rst b/docs/api_principles.rst index 8d912d08..7abbe7f7 100644 --- a/docs/api_principles.rst +++ b/docs/api_principles.rst @@ -52,7 +52,7 @@ The library is structured as follows, following a similar style to │   ├── mbar_.py │   ├── ti_.py │   └── ... - ├── convergence ### NOT IMPLEMENTED + ├── convergence │   ├── convergence.py │   └── ... ├── postprocessors @@ -64,30 +64,18 @@ The library is structured as follows, following a similar style to │   ├── mbar_matrix.py │   ├── ti_dhdl.py │   └── ... - └── workflows + └── workflows ### WORK IN PROGRESS └── ... -The :mod:`~alchemlyb.parsing` submodule contains parsers for individual MD engines, since the output files needed to perform alchemical free energy calculations vary widely and are not standardized. -Each module at the very least provides an `extract_u_nk` function for extracting reduced potentials (needed for MBAR), as well as an `extract_dHdl` function for extracting derivatives required for thermodynamic integration. -Other helper functions may be exposed for additional processing, such as generating an XVG file from an EDR file in the case of GROMACS. -All `extract\_*` functions take similar arguments (a file path, -parameters such as temperature), and produce standard outputs -(:class:`pandas.DataFrame` for reduced potentials, :class:`pandas.Series` for derivatives). +* The :mod:`~alchemlyb.parsing` submodule contains parsers for individual MD engines, since the output files needed to perform alchemical free energy calculations vary widely and are not standardized. Each module at the very least provides an `extract_u_nk` function for extracting reduced potentials (needed for MBAR), as well as an `extract_dHdl` function for extracting derivatives required for thermodynamic integration. Other helper functions may be exposed for additional processing, such as generating an XVG file from an EDR file in the case of GROMACS. All `extract\_*` functions take similar arguments (a file path, parameters such as temperature), and produce standard outputs (:class:`pandas.DataFrame` for reduced potentials, :class:`pandas.Series` for derivatives). +* The :mod:`~alchemlyb.preprocessing` submodule features functions for subsampling timeseries, as may be desired before feeding them to an estimator. So far, these are limited to `slicing`, `statistical_inefficiency`, and `equilibrium_detection` functions, many of which make use of subsampling schemes available from :mod:`pymbar`. These functions are written in such a way that they can be easily composed as parts of complex processing pipelines. +* The :mod:`~alchemlyb.estimators` module features classes *a la* **scikit-learn** that can be initialized with parameters that determine their behavior and then "trained" on a `fit` method. MBAR, BAR, and thermodynamic integration (TI) as the major methods are all implemented. Correct error estimates require the use of time series with independent samples. +* The :mod:`~alchemlyb.convergence` submodule features convenience functions/classes for doing convergence analysis using a given dataset and a chosen estimator. +* The :mod:`~alchemlyb.postprocessors` submodule contains functions to calculate new quantities or express data in different units. +* The :mod:`~alchemlyb.visualisation` submodule contains convenience plotting functions as known from, for example, `alchemical-analysis.py`_. +* The :mod:`~alchemlyb.workflows` submodule will contain complete analysis workflows that will serve as larger building blocks for complex analysis pipelines or a command line interface. -The :mod:`~alchemlyb.preprocessing` submodule features functions for subsampling timeseries, as may be desired before feeding them to an estimator. -So far, these are limited to `slicing`, `statistical_inefficiency`, and `equilibrium_detection` functions, many of which make use of subsampling schemes available from :mod:`pymbar`. -These functions are written in such a way that they can be easily composed as parts of complex processing pipelines. - -The :mod:`~alchemlyb.estimators` module features classes *a la* **scikit-learn** that can be initialized with parameters that determine their behavior and then "trained" on a `fit` method. -MBAR, BAR, and thermodynamic integration (TI) as the major methods are all implemented. -Correct error estimates require the use of time series with independent samples. - -The :mod:`~alchemlyb.convergence` submodule will feature convenience functions/classes for doing convergence analysis using a given dataset and a chosen estimator. - -The :mod:`~alchemlyb.postprocessing` submodule contains functions to calculate new quantities or express data in different units. - -The :mod:`~alchemlyb.visualization` submodule contains convenience plotting functions as known from, for example, `alchemical-analysis.py`_. All of these components lend themselves well to writing clear and flexible pipelines for processing data needed for alchemical free energy calculations, and furthermore allow for scaling up via libraries like `dask`_ or `joblib`_. diff --git a/docs/convergence.rst b/docs/convergence.rst index 14a1b480..55a4e270 100644 --- a/docs/convergence.rst +++ b/docs/convergence.rst @@ -1,3 +1,5 @@ +.. module:: alchemlyb.convergence + Using functions to estimate Convergence ======================================= @@ -31,4 +33,16 @@ Will give a plot looks like this A convergence plot of showing that the forward and backward has converged fully. -.. autofunction:: alchemlyb.convergence.forward_backward_convergence \ No newline at end of file + +Convergence functions +--------------------- + +The currently available connvergence functions: + +.. currentmodule:: alchemlyb.convergence + +.. autosummary:: + :toctree: convergence + + convergence + diff --git a/docs/convergence/alchemlyb.convergence.convergence.rst b/docs/convergence/alchemlyb.convergence.convergence.rst new file mode 100644 index 00000000..981c9b27 --- /dev/null +++ b/docs/convergence/alchemlyb.convergence.convergence.rst @@ -0,0 +1,12 @@ +Convergence analysis +==================== +.. automodule:: alchemlyb.convergence.convergence + +This module contains building blocks that perform a specific convergence analysis. They typically operate on lists of raw data and run estimators on these data sets. + + +API Reference +------------- +This submodule includes these convergence functions: + +.. autofunction:: alchemlyb.convergence.forward_backward_convergence diff --git a/docs/estimators.rst b/docs/estimators.rst index d1eceebb..af3476f1 100644 --- a/docs/estimators.rst +++ b/docs/estimators.rst @@ -1,3 +1,5 @@ +.. module:: alchemlyb.estimators + .. _estimators: Using estimators to obtain free energies diff --git a/docs/index.rst b/docs/index.rst index f9b36240..6d42c6a3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -54,10 +54,17 @@ The pandas_ package (one of our other primary dependencies) also follows `NEP 29 .. _contact: -Contributing ------------- -Contributions are very welcome. If you have bug reports or feature requests or questions then please get in touch with us through the `Issue Tracker`_. We also welcome code contributions: have a look at our `Developer Guide`_ and submit a pull request against the `alchemistry/alchemlyb`_ GitHub repository. +Getting involved +---------------- +Contributions of all kinds are very welcome. +If you have questions or want to discuss alchemlyb please post in the `alchemlyb Discussions`_. + +If you have bug reports or feature requests then please get in touch with us through the `Issue Tracker`_. + +We also welcome code contributions: have a look at our `Developer Guide`_. Open an issue with the proposed fix or change in the `Issue Tracker`_ and submit a pull request against the `alchemistry/alchemlyb`_ GitHub repository. + +.. _`alchemlyb Discussions`: https://github.com/alchemistry/alchemlyb/discussions .. _`Developer Guide`: https://github.com/alchemistry/alchemlyb/wiki/Developer-Guide .. _`Issue Tracker`: https://github.com/alchemistry/alchemlyb/issues .. _`alchemistry/alchemlyb`: https://github.com/alchemistry/alchemlyb diff --git a/docs/parsing.rst b/docs/parsing.rst index 4af2d65b..c3a4181c 100644 --- a/docs/parsing.rst +++ b/docs/parsing.rst @@ -1,3 +1,6 @@ +.. module:: alchemlyb.parsing + + Parsing data files ================== **alchemlyb** features parsing submodules for getting raw data from different software packages into common data structures that can be used directly by its :ref:`subsamplers ` and :ref:`estimators `. diff --git a/docs/postprocessing.rst b/docs/postprocessing.rst index d7451108..e6e4dc80 100644 --- a/docs/postprocessing.rst +++ b/docs/postprocessing.rst @@ -1,3 +1,5 @@ +.. module:: alchemlyb.postprocessors + .. _postprocessing: Tools for postprocessing diff --git a/docs/preprocessing.rst b/docs/preprocessing.rst index 44ba8baa..dcd2ad19 100644 --- a/docs/preprocessing.rst +++ b/docs/preprocessing.rst @@ -1,3 +1,6 @@ +.. module:: alchemlyb.preprocessing + + Preprocessing datasets ====================== It is often the case that some initial pre-processing of raw datasets are desirable before feeding these to an estimator. diff --git a/docs/visualisation.rst b/docs/visualisation.rst index 2390cc63..e25e1266 100644 --- a/docs/visualisation.rst +++ b/docs/visualisation.rst @@ -1,3 +1,5 @@ +.. module:: alchemlyb.visualisation + Visualisation of the results ============================ It is quite often that the user want to visualise the results to gain diff --git a/setup.py b/setup.py index d9930f6d..81f19a13 100755 --- a/setup.py +++ b/setup.py @@ -31,6 +31,7 @@ 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3.8', 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', 'Topic :: Scientific/Engineering', 'Topic :: Scientific/Engineering :: Bio-Informatics', 'Topic :: Scientific/Engineering :: Chemistry', diff --git a/src/alchemlyb/convergence/convergence.py b/src/alchemlyb/convergence/convergence.py index 4ece921c..e626f2dc 100644 --- a/src/alchemlyb/convergence/convergence.py +++ b/src/alchemlyb/convergence/convergence.py @@ -7,13 +7,13 @@ def forward_backward_convergence(df_list, estimator='mbar', num=10): - ''' The forward and backward convergence of the free energy estimate. + '''Forward and backward convergence of the free energy estimate. - Generate the free energy estimate as a function of time in both - directions, with the specified number of points in the time. For example, - setting `num` to 10 would give the forward convergence which is the free - energy estimate from the first 10%, 20%, 30% .. of the data. The - Backward would give the estimate from the last 10%, 20%, 30% .. of the + Generate the free energy estimate as a function of time in both directions, + with the specified number of equally spaced points in the time. For + example, setting `num` to 10 would give the forward convergence which is + the free energy estimate from the first 10%, 20%, 30%, ... of the data. The + Backward would give the estimate from the last 10%, 20%, 30%, ... of the data. Parameters @@ -44,6 +44,7 @@ def forward_backward_convergence(df_list, estimator='mbar', num=10): .. versionadded:: 0.6.0 + ''' logger = logging.getLogger('alchemlyb.convergence.' 'forward_backward_convergence')