Merge branch 'master' into 71-joss-paper

.git-blame-ignore-revs

@@ -0,0 +1,6 @@
+# initial blackify #280
+0095be256b369673526dff7ed754cc874f4128a2
+
+# ensure all recent changes were black-formatted (prep for 2.4.0)
+d7058a5a8e489a9213ed499e999bb226397bc708
+

.gitignore

@@ -10,3 +10,7 @@ __pycache__
 *~
 dist/
 
+# auto-generated files
+_version.py
+
+

AUTHORS

@@ -16,6 +16,9 @@ GitHub handle are preferred. The repository history at
 https://github.com/alchemistry/alchemlyb and the CHANGES file show
 individual code contributions.
 
+New contributors should add themselves to the end of this file AND to
+the file CITATION.cff at the end of the top-level authors list.
+
 
 Chronological list of authors
 -----------------------------
@@ -53,3 +56,6 @@ Chronological list of authors
 
 2023
   - Haoxi Li (@hl2500)
+
+2024
+  - Jennifer A. Clark (@jaclark5)

CHANGES

@@ -12,7 +12,19 @@ The rules for this file:
   * accompany each entry with github issue/PR number (Issue #xyz)
   * release numbers follow "Semantic Versioning" https://semver.org
 
-------------------------------------------------------------------------------
+
+09/17/2024 jaclark5, orbeckst
+
+  * 2.4.0
+
+Enhancements
+  - Addition of `block_average` function in both `convergence` and 
+    `visualization` (Issue #380, PR #381)
+  - add CITATION.cff file with all authors from AUTHORS (issue #394, PR #395)
+
+Changes
+  - modernize build system: replaced setup.py,cfg with pyproject.toml (#385)
+
 08/24/2024 xiki-tempula
 
   * 2.3.2

CITATION.cff

@@ -0,0 +1,244 @@
+# -*- coding: utf-8 -*-
+# This CITATION.cff file was initially generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: alchemlyb
+message: >-
+  If you use this software, please cite it using the
+  preferred citation together with any other references.
+type: software
+authors:
+  - email: david@datryllic.com
+    given-names: David L.
+    family-names: Dotson
+    orcid: 'https://orcid.org/0000-0001-5879-2942'
+    affiliation: Datryllic LLC
+  - given-names: Ian M.
+    family-names: Kenney
+    orcid: 'https://orcid.org/0000-0002-9749-8866'
+    affiliation: Kenney Consulting, LLC    
+  - given-names: Oliver
+    family-names: Beckstein
+    email: obeckste@asu.edu
+    affiliation: Arizona State University
+    orcid: 'https://orcid.org/0000-0003-1340-0831'
+  - given-names: Shuai
+    family-names: Liu
+    orcid: 'https://orcid.org/0000-0002-8632-633X'
+    affiliation: Silicon Therapeutics LLC
+  - given-names: Travis
+    family-names: Jensen
+  - given-names: Bryce
+    family-names: Allen
+    orcid: 'https://orcid.org/0000-0002-0804-8127'
+    affiliation: Differentiated Therapeutics
+  - given-names: Dominik
+    family-names: Wille
+    affiliation: Freie Universität Berlin
+  - given-names: Victoria
+    family-names: Lim
+    orcid: 'https://orcid.org/0000-0003-4030-9312'
+    affiliation: University of California Irvine
+  - given-names: Hyungro
+    family-names: Lee
+    orcid: 'https://orcid.org/0000-0002-4221-7094'
+    affiliation: Pacific Northwest National Laboratory
+  - given-names: Mohammad Soroush
+    family-names: Barhaghi
+    orcid: 'https://orcid.org/0000-0001-8226-7347'
+    affiliation: Wayne State University
+  - given-names: Zhiyi
+    family-names: Wu
+    affiliation: Exscientia plc
+    orcid: 'https://orcid.org/0000-0002-7615-7851'
+    email: william@zhiyiwu.me
+  - given-names: Wei-Tse
+    family-names: Hsu
+    orcid: https://orcid.org/0000-0001-6167-5480
+    affiliation: University of Colorado Boulder    
+  - given-names: Alexander
+    family-names: Schlaich
+    orcid: 'https://orcid.org/0000-0002-4250-363X'
+    affiliation: University of Stuttgart
+  - given-names: Jérôme
+    family-names: Hénin
+    orcid: 'https://orcid.org/0000-0003-2540-4098'
+    affiliation: CNRS
+  - given-names: Thomas T.
+    family-names: Joseph
+    orcid: 'https://orcid.org/0000-0003-1323-3244'
+    affiliation: University of Pennsylvania
+  - given-names: Irfan
+    family-names: Alibay
+    orcid: 'https://orcid.org/0000-0001-5787-9130'
+    affiliation: Open Molecular Software Foundation
+  - given-names: Pascal T.
+    family-names: Merz
+    affiliation: PM Scientific Consulting
+    orcid: 'https://orcid.org/0000-0002-7045-8725'
+  - given-names: Domenico
+    family-names: Marson
+    orcid: 'https://orcid.org/0000-0003-1839-9868'
+    affiliation: University of Trieste
+  - given-names: Shujie
+    family-names: Fan
+    orcid: 'https://orcid.org/0000-0002-0271-2760'
+    affiliation: Arizona State University
+  - given-names: Jan
+    family-names: Janssen
+    affiliation: Max-Planck-Institut for Sustainable Materials
+    orcid: 'https://orcid.org/0000-0001-9948-7119'
+  - given-names: Haoxi
+    family-names: Li
+    orcid: 'https://orcid.org/0009-0004-8369-1042'
+    affiliation: University of North Carolina
+  - given-names: Helmut
+    family-names: Carter
+    orcid: https://orcid.org/0000-0003-0273-4107    
+    affiliation: City University of New York
+  - given-names: David
+    family-names: Mobley
+    orcid: 'https://orcid.org/0000-0002-1083-5533'
+    affiliation: University of California Irvine    
+  - given-names: Michael R.
+    family-names: Shirts
+    orcid: 'https://orcid.org/0000-0003-3249-1097'
+    affiliation: University of Colorado Boulder
+  - given-names: Jennifer A.
+    family-names: Clark
+    orcid: https://orcid.org/0000-0003-4897-5651
+    affiliation: National Institute of Standards and Technology
+identifiers:
+  - type: swh
+    value: 'swh:1:dir:4cd266754be413312ee7ef3f1f7fbe05b38192cf'
+    description: >-
+      The Software Heritage identifier for the top level
+      directory of the repository.
+repository-code: 'https://github.com/alchemistry/alchemlyb'
+url: 'https://alchemlyb.readthedocs.io'
+abstract: >-
+  alchemlyb is an open-source Python software package for
+  the analysis of alchemical free energy calculations. Its
+  functionality contains individual composable building
+  blocks for all aspects of a full typical free energy
+  analysis workflow, starting with the extraction of raw
+  data from the output of diverse molecular simulation
+  packages, moving on to data preprocessing tasks such as
+  decorrelation of time series, using various estimators to
+  derive free energy estimates from simulation samples, and
+  finally providing quality analysis tools for data
+  convergence checking and visualization. alchemlyb also
+  contains high-level end-to-end workflows that combine
+  multiple building blocks into a user-friendly analysis
+  pipeline from the initial data input stage to the final
+  results.
+keywords:
+  - Python
+  - free energy
+  - molecular dynamics
+  - alchemistry
+license: BSD-3-Clause
+preferred-citation:
+  title: 'alchemlyb: the simple alchemistry library'
+  authors:
+    - given-names: Zhiyi
+      family-names: Wu
+      affiliation: Exscientia plc
+      orcid: 'https://orcid.org/0000-0002-7615-7851'
+      email: william@zhiyiwu.me  
+    - given-names: David L.
+      family-names: Dotson
+      orcid: 'https://orcid.org/0000-0001-5879-2942'
+      affiliation: Arizona State University
+    - given-names: Irfan
+      family-names: Alibay
+      orcid: 'https://orcid.org/0000-0001-5787-9130'
+      affiliation: Open Molecular Software Foundation
+    - given-names: Bryce
+      family-names: Allen
+      orcid: 'https://orcid.org/0000-0002-0804-8127'
+      affiliation: Differentiated Therapeutics
+    - given-names: Mohammad Soroush
+      family-names: Barhaghi
+      orcid: 'https://orcid.org/0000-0001-8226-7347'
+      affiliation: Wayne State University
+    - given-names: Jérôme
+      family-names: Hénin
+      orcid: 'https://orcid.org/0000-0003-2540-4098'
+      affiliation: CNRS
+    - given-names: Thomas T.
+      family-names: Joseph
+      orcid: 'https://orcid.org/0000-0003-1323-3244'
+      affiliation: University of Pennsylvania      
+    - given-names: Ian M.
+      family-names: Kenney
+      orcid: 'https://orcid.org/0000-0002-9749-8866'
+      affiliation: Arizona State University
+    - given-names: Hyungro
+      family-names: Lee
+      orcid: 'https://orcid.org/0000-0002-4221-7094'
+      affiliation: Pacific Northwest National Laboratory
+    - given-names: Haoxi
+      family-names: Li
+      orcid: 'https://orcid.org/0009-0004-8369-1042'
+      affiliation: University of North Carolina      
+    - given-names: Victoria
+      family-names: Lim
+      orcid: 'https://orcid.org/0000-0003-4030-9312'
+      affiliation: University of California Irvine      
+    - given-names: Shuai
+      family-names: Liu
+      orcid: 'https://orcid.org/0000-0002-8632-633X'
+      affiliation: Silicon Therapeutics LLC
+    - given-names: Domenico
+      family-names: Marson
+      orcid: 'https://orcid.org/0000-0003-1839-9868'
+      affiliation: University of Trieste
+    - given-names: Pascal T.
+      family-names: Merz
+      affiliation: PM Scientific Consulting
+      orcid: 'https://orcid.org/0000-0002-7045-8725'      
+    - given-names: Alexander
+      family-names: Schlaich
+      orcid: 'https://orcid.org/0000-0002-4250-363X'
+      affiliation: University of Stuttgart
+    - given-names: David
+      family-names: Mobley
+      orcid: 'https://orcid.org/0000-0002-1083-5533'
+      affiliation: University of California Irvine
+    - given-names: Michael R.
+      family-names: Shirts
+      orcid: 'https://orcid.org/0000-0003-3249-1097'
+      affiliation: University of Colorado Boulder
+    - given-names: Oliver
+      family-names: Beckstein
+      email: obeckste@asu.edu
+      affiliation: Arizona State University
+      orcid: 'https://orcid.org/0000-0003-1340-0831'
+  type: 'article'
+  year: 2024
+  journal: 'Journal of Open Source Software'
+  doi: '10.21105/joss.06934'
+references:
+  - title: Statistically optimal analysis of samples from multiple equilibrium states
+    authors:
+      - family-names: Shirts
+        given-names: Michael R
+      - family-names: Chodera
+        given-names: John D
+    type: 'article'
+    pages: '124105'
+    year: '2008'
+    journal: Journal of Chemical Physics
+    doi: '10.1063/1.2978177'
+  - title: A Simple Method for Automated Equilibration Detection in Molecular Simulations
+    authors:
+      - family-names: Chodera
+        given-names: John D.
+    type: 'article'
+    pages: '1799–1805'
+    year: '2016'
+    journal: 'Journal of Chemical Theory and Computation'
+    doi: '10.1021/acs.jctc.5b00784'
+

docs/conf.py

@@ -67,12 +67,11 @@
 # We always display the full release string; if something else is
 # desired, see the commented out code
 
-from alchemlyb._version import get_versions
-
-release = get_versions()["version"]
-del get_versions
+import alchemlyb
 
+release = alchemlyb.__version__
 version = release
+
 # version = release.split("+")[0]  # only major.minor.patch
 # version = "."join(release.split(".")[:2])  # only major.minor
 

docs/convergence.rst

@@ -75,6 +75,31 @@ is, where 0 fully-unequilibrated and 1.0 is fully-equilibrated. ::
     >>> value = A_c(dhdl_list, tol=2)
     0.7085
 
+Block Average
+--------------
+If one obtains suspicious results from the forward / backward convergence plot,
+it may be useful to view the block averages of the change in free energy using
+:func:`~alchemlyb.convergence.block_average` and
+:func:`~alchemlyb.visualisation.plot_block_average` over the course of each 
+step in lambda individually, the following example is for :math:`\lambda` = 0
+
+    >>> from alchemtest.gmx import load_benzene
+    >>> from alchemlyb.parsing.gmx import extract_u_nk
+    >>> from alchemlyb.visualisation import plot_block_average
+    >>> from alchemlyb.convergence import block_average
+
+    >>> bz = load_benzene().data
+    >>> data_list = [extract_u_nk(xvg, T=300) for xvg in bz['Coulomb']]
+    >>> df = block_average(data_list, 'mbar')
+    >>> ax = plot_block_average(df)
+    >>> ax.figure.savefig('dF_t_block_average.png')
+
+Will give a plot looks like this
+
+.. figure:: images/dF_t_block_average.png
+
+   A plot of the free energy divided into block averages showing consistency/inconsistency 
+   across the trajectory.
 
 Convergence functions
 ---------------------

docs/convergence/alchemlyb.convergence.convergence.rst

@@ -15,3 +15,5 @@ All convergence functions are located in this submodule but for convenience they
 .. autofunction:: alchemlyb.convergence.fwdrev_cumavg_Rc
 
 .. autofunction:: alchemlyb.convergence.A_c		  
+
+.. autofunction:: alchemlyb.convergence.block_average

docs/visualisation.rst

@@ -19,6 +19,7 @@ Plotting Functions
     plot_ti_dhdl
     plot_dF_state
     plot_convergence
+    plot_block_average
 
 .. _plot_overlap_matrix:
 

docs/visualisation/alchemlyb.visualisation.plot_block_average.rst

@@ -0,0 +1,6 @@
+alchemlyb.visualisation.plot\_block\_average
+=============================================
+
+.. currentmodule:: alchemlyb.visualisation
+
+.. autofunction:: plot_block_average