Merge pull request #261 from alchemistry/finalize-1.0.0

finalize 1.0.0

CHANGES

@@ -13,55 +13,59 @@ The rules for this file:
   * release numbers follow "Semantic Versioning" https://semver.org
 
 ------------------------------------------------------------------------------
-??/??/2022 orbeckst, xiki-tempula
+10/31/2022 orbeckst, xiki-tempula, DrDomenicoMarson 
 
   * 1.0.0
 
 Changes
+  - The 1.x release only supports pymbar 3.x; alchemlyb 2.x will only support
+    pymbar >= 4.0. (#205)
   - Default the units in plot_dF_state, plot_convergence and plot_ti_dhdl to
     None. Remove the array input for plot_convergence (issue #247, PR #260).
   - Now AMBER parser raises an exception when an inconsinstency in the input
     file is found, instead of ignoring the file (issues #227 #238, PR #256)
-  - Now AMBER parser raises an exception when an inconsinstency in 
-    MBAR data is found (PR #253)
+  - Now AMBER parser raises an exception when an inconsistency in MBAR data is
+    found (PR #253)
   - Drop support for py3.7 (Issue #179, PR #214)
   - forward_backward_convergence will use AutoMBAR as backend when `MBAR` is
     selected as the estimator (PR #114).
   - AutoMBAR accepts the `method` argument (PR #114).
   - Refactor the subsampling module to unify the behaviour of
     equilibrium_detection and statistical_inefficiency (PR #218).
-  - Remove the ignore_warnings flag in ABFE workflow. (PR #231)
   - delta_f_, d_delta_f_, states_ are view of the original object in estimator
     (issue #246, PR #252).
 
 
 Enhancements
   - Add u_nk2series and dhdl2series to convert u_nk and dHdl to series (PR
     #218).
-  - Add remove_burnin keyword to decorrelate_u_nk and decorrelate_dhdl (PR #218).
+  - Add remove_burnin keyword to decorrelate_u_nk and decorrelate_dhdl (PR
+    #218).
   - Add a base class for workflows (PR #188).
-  - Add the ABFE workflow (PR #114).
-  - Add R_c and A_c for "fractional equilibration time" convergence analysis 
+  - Add the ABFE workflow (PR #114, PR #231).
+  - Add R_c and A_c for "fractional equilibration time" convergence analysis
     (issue #104, PR #239)
   - Add the keyword arg final_error to plot_convergence (#249)
 
 
 Fixes
   - documented conda installation (available since 0.6.0) (#192)
-  - AMBER parsers now use 'ntpr' information to read time properly (issue #221, PR #224)
+  - AMBER parsers now use 'ntpr' information to read time properly (issue #221,
+    PR #224)
   - AMBER parsers now skip the reading of averages (issue #226, PR #230)
-  - AMBER parsers now check if the T provided by the user is the same
-    at which the simulations were run (issue #225, PR #232)
+  - AMBER parsers now check if the T provided by the user is the same at which
+    the simulations were run (issue #225, PR #232)
   - changed how int/float are read from AMBER files (issue #229, PR #235)
-  - substitute the any_none() function with a check "if None in" in the AMBER parser (issue #236, PR #237)
-  - For ABFE workflow, dHdl will only be read when a TI estimator is chosen.
-    Similarly, u_nk will only be read when FEP estimators are chosen. (PR #231)
-  - All parsers now have a 'extract(file, T)' method that returns a dict with both
-    "dHdl" and "u_nk" data (or None). THe AMBER parser when using this function will read the 
-    file just once, extracting all data at once. (issue #222, PR #240)
+  - substitute the any_none() function with a check "if None in" in the AMBER
+    parser (issue #236, PR #237)
+  - All parsers now have a 'extract(file, T)' method that returns a dict with
+    both "dHdl" and "u_nk" data (or None). The AMBER parser when using this
+    function will read the file just once, extracting all data at once. (issue
+    #222, PR #240)
   - Fix dhdl2series and u_nk2series would not reattach the unit. (PR #248)
-  - Removed the 'dhdl' keyword for uncorrelating the u_nk (see `u_nk2series()`). Use 'dE'
-    as an alternative or use 'all' (instead of the deprecated 'dhdl_all')  (PR #250).
+  - Removed the 'dhdl' keyword for uncorrelating the u_nk (see
+    `u_nk2series()`). Use 'dE' as an alternative or use 'all' (instead of the
+    deprecated 'dhdl_all') (PR #250).
 
 
 07/22/2022 xiki-tempula, IAlibay, dotsdl, orbeckst, ptmerz

docs/conf.py

@@ -50,10 +50,11 @@
 
 # General information about the project.
 project = u'alchemlyb'
-author = u'''David Dotson, Ian Kenney, Oliver Beckstein, Shuai Liu,
-Travis Jensen, Bryce Allen, Dominik Wille, Victoria Lim, Hyungro Lee,
-Mohammad S. Barhaghi, Zhiyi Wu'''
-copyright = u'2017-2020, ' + author
+author = u'''Irfan Alibay, Bryce Allen, Mohammad S. Barhaghi, Oliver
+Beckstein, David Dotson, Jérôme Hénin, Travis Jensen, Thomas
+T. Joseph, Ian Kenney, Hyungro Lee, Victoria Lim, Shuai Liu, Domenico
+Marson, Pascal Merz, Alexander Schlaich, Dominik Wille, Zhiyi Wu'''
+copyright = u'2017-2022, ' + author
 
 
 # The version info for the project you're documenting, acts as replacement for

docs/convergence.rst

@@ -1,19 +1,16 @@
 .. module:: alchemlyb.convergence
 
-Using functions to estimate Convergence
-=======================================
+Assessing convergence
+=====================
 
-For a result to be valid, we need to ensure that longer simulation time
-would not result in different results. Various functions will be provided in
-this module to estimate the convergence of the estimate and help user determine
-the simulation end point.
+For a result to be valid, we need to ensure that longer simulation time would not result in different results, i.e., that our results are *converged*. The :mod:`alchemlyb.convergence`  module provides functions to assess the convergence of free energy estimates or other quantities. 
 
 Time Convergence
 ----------------
 One way of determining the simulation end point is to compute and plot the
 forward and backward convergence of the estimate using
 :func:`~alchemlyb.convergence.forward_backward_convergence` and
-:func:`~alchemlyb.visualisation.plot_convergence`. ::
+:func:`~alchemlyb.visualisation.plot_convergence` [Klimovich2015]_. ::
 
     >>> from alchemtest.gmx import load_benzene
     >>> from alchemlyb.parsing.gmx import extract_u_nk
@@ -35,9 +32,8 @@ Will give a plot looks like this
 
 Fractional equilibration time
 -----------------------------
-
 Another way of assessing whether the simulation has converged is to check the
-energy files. In [Fan2021]_, :math:`R_c` and
+energy files. In [Fan2021]_ (and [Fan2020]_), :math:`R_c` and
 :math:`A_c` are two criteria of checking the
 convergence. :func:`~alchemlyb.convergence.fwdrev_cumavg_Rc` takes a decorrelated
 :class:`pandas.Series` as input and gives the metric
@@ -76,28 +72,19 @@ is, where 0 fully-unequilibrated and 1.0 is fully-equilibrated. ::
     >>>     decorrelated = decorrelate_dhdl(dhdl, remove_burnin=True)
     >>>     decorrelated = dhdl2series(decorrelated)
     >>>     dhdl_list.append(decorrelated)
-    >>> value = A_c(dhdl_list)
+    >>> value = A_c(dhdl_list, tol=2)
     0.7085
 
 
 Convergence functions
 ---------------------
 
-The currently available connvergence functions:
+Convergence functions are available from :mod:`alchemlyb.convergence`. Internally, they are imported from submodules, as documented below.
 
 .. currentmodule:: alchemlyb.convergence
 
 .. autosummary::
     :toctree: convergence
 
-    forward_backward_convergence
-    fwdrev_cumavg_Rc
-    A_c
-
-References
-----------
-
-.. [Fan2021] Fan, S., Nedev, H., Vijayan, R., Iorga, B.I., and Beckstein, O.
-    (2021). Precise force-field-based calculations of octanol-water partition
-    coefficients for the SAMPL7 molecules. Journal of Computer-Aided Molecular
-    Design 35, 853–87
+    convergence
+

docs/convergence/alchemlyb.convergence.convergence.rst

@@ -1,12 +1,17 @@
-Convergence analysis
-====================
+Convergence API Reference
+=========================
 .. 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.
+The :mod:`alchemlyb.convergence.convergence` module contains building blocks that perform a specific convergence analysis. They typically operate on lists of raw data and either run estimators on these data sets to obtain free energies as a function of the amount of data or they directly assess the convergence of the raw data.
 
+.. Note::
+   Read the original literature to learn the exact meaning of parameters and how to interpret the output of the convergence analysis.
 
-API Reference
--------------
-This submodule includes these convergence functions:
+
+All convergence functions are located in this submodule but for convenience they are also made available from :mod:`alchemlyb.convergence`, as shown here:
 
 .. autofunction:: alchemlyb.convergence.forward_backward_convergence
+
+.. autofunction:: alchemlyb.convergence.fwdrev_cumavg_Rc
+
+.. autofunction:: alchemlyb.convergence.A_c		  

docs/index.rst

@@ -14,10 +14,21 @@ 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* and the API is still somewhat in flux. 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. See :ref:`contact` for how to get in touch if you have questions or find problems.
+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.
+
+.. 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`_)
+
+See :ref:`contact` for how to get in touch if you have questions or find problems.
+
 
 .. _`dask`: http://dask.pydata.org
 .. _`semantic versioning`: https://semver.org
+.. _`pymbar`: https://github.com/choderalab/pymbar
+.. _`discussion #205`: https://github.com/alchemistry/alchemlyb/discussions/205
+.. _`issue #207`: https://github.com/alchemistry/alchemlyb/issues/207
+
 
 Core philosophy
 ---------------
@@ -81,6 +92,7 @@ We also welcome code contributions: have a look at our `Developer Guide`_. Open
     postprocessing
     visualisation
     workflows
+    references
 
 .. toctree::
    :maxdepth: 1

docs/references.rst

@@ -0,0 +1,25 @@
+.. -*- coding: utf-8 -*-
+
+References
+==========
+
+
+.. [Klimovich2015] Klimovich, P.V., M. R. Shirts, and D. L. Mobley. (2015)
+   Guidelines for the analysis of free energy calculations. Journal of
+   Computer-Aided Molecular Design 29, 397-411. doi:
+   `10.1007/s10822-015-9840-9 <https://doi.org/10.1007/s10822-015-9840-9>`_.
+		   
+.. [Fan2020] Fan, S., B. I. Iorga, and O. Beckstein. (2020). Prediction of
+   octanol-water partition coefficients for the SAMPL6-log P molecules using
+   molecular dynamics simulations with OPLS-AA, AMBER and CHARMM force fields.
+   Journal of Computer-Aided Molecular Design 34,
+   543–560. doi:`10.1007/s10822-019-00267-z
+   <https://doi.org/10.1007/s10822-019-00267-z>`_.
+
+.. [Fan2021] Fan, S., Nedev, H., Vijayan, R., Iorga, B.I., and Beckstein, O.
+   (2021). Precise force-field-based calculations of octanol-water partition
+   coefficients for the SAMPL7 molecules. Journal of Computer-Aided Molecular
+   Design 35, 853–887. doi: `10.1007/s10822-021-00407-4
+   <https://doi.org/10.1007/s10822-021-00407-4>`_.
+   
+   

docs/visualisation.rst

@@ -184,6 +184,3 @@ Will give a plot looks like this
    A convergence plot of showing that the forward and backward has converged
    fully.
 
-.. [Klimovich2015] Klimovich, P.V., Shirts, M.R. & Mobley, D.L. Guidelines for
-   the analysis of free energy calculations. J Comput Aided Mol Des 29, 397–411
-   (2015). https://doi.org/10.1007/s10822-015-9840-9

docs/workflows.rst

@@ -15,8 +15,8 @@ for doing automatic absolute binding free energy (ABFE) analysis.
 .. currentmodule:: alchemlyb.workflows
 
 .. autosummary::
-    :toctree: workflows
+   :toctree: workflows
 
-    base
-    ABFE
+   base
+   ABFE
 

docs/workflows/alchemlyb.workflows.base.rst

@@ -1,9 +1,10 @@
 The base workflow
 =================
+.. automodule:: alchemlyb.workflows.base
 
-The :class:`alchemlyb.workflows.base.WorkflowBase` provides a basic API
-template for the workflow development.
-The workflow should be able to run in an automatic fashion. ::
+The :class:`alchemlyb.workflows.base.WorkflowBase` class provides a
+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,
@@ -25,6 +26,8 @@ step-by-step fashion. ::
 
 API Reference
 -------------
+.. currentmodule:: alchemlyb.workflows.base
+
 .. autoclass:: alchemlyb.workflows.base.WorkflowBase
     :members:
     :inherited-members: