Skip to content

Commit

Permalink
Merge pull request #181 from alchemistry/prep-release-060
Browse files Browse the repository at this point in the history
prepare release 0.6.0
  • Loading branch information
orbeckst authored Dec 29, 2021
2 parents a1c0b09 + f1efb6c commit a8ac1a1
Show file tree
Hide file tree
Showing 14 changed files with 100 additions and 47 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 2 additions & 3 deletions CHANGES
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
43 changes: 31 additions & 12 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
<http://pymbar.readthedocs.io/>`_ 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
Expand All @@ -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%
Expand Down
30 changes: 9 additions & 21 deletions docs/api_principles.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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`_.

Expand Down
16 changes: 15 additions & 1 deletion docs/convergence.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. module:: alchemlyb.convergence

Using functions to estimate Convergence
=======================================

Expand Down Expand Up @@ -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

Convergence functions
---------------------

The currently available connvergence functions:

.. currentmodule:: alchemlyb.convergence

.. autosummary::
:toctree: convergence

convergence

12 changes: 12 additions & 0 deletions docs/convergence/alchemlyb.convergence.convergence.rst
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions docs/estimators.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. module:: alchemlyb.estimators

.. _estimators:

Using estimators to obtain free energies
Expand Down
13 changes: 10 additions & 3 deletions docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions docs/parsing.rst
Original file line number Diff line number Diff line change
@@ -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 <subsampling>` and :ref:`estimators <estimators>`.
Expand Down
2 changes: 2 additions & 0 deletions docs/postprocessing.rst
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
.. module:: alchemlyb.postprocessors

.. _postprocessing:

Tools for postprocessing
Expand Down
3 changes: 3 additions & 0 deletions docs/preprocessing.rst
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
2 changes: 2 additions & 0 deletions docs/visualisation.rst
Original file line number Diff line number Diff line change
@@ -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
Expand Down
1 change: 1 addition & 0 deletions setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
13 changes: 7 additions & 6 deletions src/alchemlyb/convergence/convergence.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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')
Expand Down

0 comments on commit a8ac1a1

Please sign in to comment.