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: