CHANGES

# -*- tab-width: 2; indent-tabs-mode: nil; coding: utf-8 -*-
====================
 alchemlyb CHANGELOG
=====================

The rules for this file:
  * entries are sorted newest-first.
  * summarize sets of changes - don't reproduce every git log comment here.
  * don't ever delete anything.
  * keep the format consistent (79 char width, M/D/Y date format) and do not
    use tabs but use spaces for formatting
  * accompany each entry with github issue/PR number (Issue #xyz)
  * release numbers follow "Semantic Versioning" https://semver.org

------------------------------------------------------------------------------
??/??/2024 orbeckst

  * 2.3.1

Changes:
  - alchemlyb adopts SPEC 0 (replaces NEP 29)
    https://scientific-python.org/specs/spec-0000/


21/05/2024 xiki-tempula

  * 2.3.0

Changes
  - Default value for keyword argument `initial_nk` of the MBAR estimator was
    changed to "BAR" (run an initial BAR calculation before MBAR) instead of 
    `None` (start from all zeros) as this change provides a sizable speedup (PR #357)
    
Enhancements
  - `forward_backward_convergence` uses the bootstrap error when the statistical error
    is too large. (PR #358)
  - `BAR` result is used as initial guess for `MBAR` estimator. (PR #357)
  - `forward_backward_convergence` uses the result from the previous step as the initial guess for the next step. (PR #357)

06/04/2024 hl2500, xiki-tempula

  * 2.2.0

Changes
  - Require pandas >= 2.1 (PR #340)
  - For pandas>=2.1, metadata will be loaded from the parquet file (issue #331, PR #340).
  - add support for Python 3.12, remove Python 3.8 support (issue #341, PR #304).

Enhancements
  - Add a TI estimator using gaussian quadrature to calculate the free energy.
    (issue #302, PR #304)
  - Warning issued when the series is `None` for `statistical_inefficiency`
    (issue #337, PR #338)
  - ValueError issued when `df` and `series` for `statistical_inefficiency`
    doesn't have the same length (issue #337, PR #338)

Fixes
  - data_fraction column in workflow.convergence won't be affected by the
    unit conversion (issue #350, PR#319).
  

22/06/2023 xiki-tempula

  * 2.1.0

Changes
  - ValueError raised if concatenated amber output file is passed to amber
    parser (issue #315, PR #326).
  - Change the % based string formatting to {} based string formatting (issue #323, PR #324).
  - Use loguru instead of logging for log (issue #301, PR #303).

Enhancements
  - "Statistical inefficiency" is logged at debug level for equilibrium_detection
    and statistical_inefficiency (issue #295, PR#325).
  - Add a parser to read serialised pandas dataframe (parquet) (issue #316, PR#317).
  - workflow.ABFE allow parquet as input (issue #316, PR#317).
  - Allow MBAR estimator to use bootstrap to compute error (issue #320, PR#322).

Fixes
  - Fix the case where visualisation.plot_convergence would fail when the final
    error is NaN (issue #318, PR#319).

DeprecationWarning
  - The default MBAR error estimator in workflow.ABFE.estimate will change from
    analytic to bootstrap=50 in 2.2.0 (issue #320, PR#322).


06/04/2023 xiki-tempula

  * 2.0.1

Fixes
  - Fix the dE method in u_nk2series to use the difference between two
    lambda columns instead of using the next lambda column or the previous
    column for the last window (issue #299, PR #300).
  - work around hanging tests on Mac M1 by using Path.glob instead of glob.glob
    in ABFE workflow (issue #309, PR #310).


12/12/2022 xiki-tempula, orbeckst

  * 2.0.0

Changes
  - use pymbar 4 as backend; this release is incompatible with
    pymbar 3.x (issue #207, PR #268, discussion #205).
  - The default for keyword argument `method` in estimators.MBAR was changed
    from "hybr" to "robust" (issue #207, PR #268).

Enhancements
  - Raise ValueError when no file has been matched in workflow.ABFE (PR #289).
  - In workflows, the output folder will be created if it did not exist before
    (PR #290).
  
Removals
  - The AutoMBAR estimator was removed because pymbar 4's MBAR contains
    equivalent functionality. (issue #284)


12/09/2022 DrDomenicoMarson, xiki-tempula, orbeckst

  * 1.0.1

Fixes
  - make workflow.ABFE handle 0 as input to forwrev instead of crashing
    (issue #276, PR #282).
  - Remove most of the iloc in the tests (issue #202, PR #254).
  - AMBER parser now raises ValueError when the initial simulation time
    is not found (issue #272, PR #273).
  - The regex in the AMBER parser now reads also 'field=value' pairs where
    there are no spaces around the equal sign (issue #272, PR #273).    
  - Pre-processing function slicing will not drop NaN rows (issue
    #274, PR #275).
    
Deprecations
  - deprecate AutoMBAR for removal in 2.0 because pymbar 4 already contains
    equivalent functionality (issue #284, PR #285).

Internal Enhancements (do not affect API)
  - Blackfy the codebase (PR #280).
  - Refactor the test to make all the parsing done at conftest level
    (issue #206, PR #278).


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 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).
  - 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 a base class for workflows (PR #188).
  - 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)
  - 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)


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 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)
  - 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)
  - 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).


07/22/2022 xiki-tempula, IAlibay, dotsdl, orbeckst, ptmerz

  * 0.7.0

Changes
  - Deployment to PyPI is now done automatically using github actions
    (Issue #193)
  - gmx parser now defaults to dropping NaN and corrupted lines (filter=True) 
    (#171, PR #183)
  - remove broken .zip support from util.anyopen() (PR #197)

Enhancements
  - Add filter function to gmx.extract to make it more robust (PR #183): can filter 
    incomplete/corrupted lines (#126, #171) with filter=True.
  - Add support to util.anyopen() for taking filelike objects (PR #197)

Fixes
  - Fixes setup.py and setup.cfg to prevent installations with Python versions
    lower than 3.7 (Issue #193)
  - added AutoMBAR to convergence analysis (#189)
  - Fixed subsampling in statistical_inefficiency when lower or step keywords
    are used (Issue #198, PR #199)


12/28/2021 schlaicha, xiki-tempula, jhenin, ttjoseph, orbeckst

  * 0.6.0

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).
    Various malformations of input files are detected, where lambdas do not
    monotonically increase or decrease, or are inconsistent or missing.
  - Convenience function for decorrelating u_nk and dHdl (PR #163).
  - Time convergence function forward_backward_convergence
    introduced and plot_convergence now takes dataframe from
    forward_backward_convergence as input (PR #168).
  - Automatic MBAR solver with fall back (issue #170, PR #172)

Fixes
  - Subsampling now works with bounds and step (PR #167, issue #166).
  - AMBER parser logger now always logs to alchemlyb.parsers.Amber
    instead of the root logger (PR #173)
  - updated deprecated pandas aggregation, now using groupby(level).agg (#175)


09/17/2021 xiki-tempula, orbeckst

  * 0.5.1

Changes (not affecting code)
  - update the Mission to also include general and robust workflows (discussion
    #159, issue #160, PR #161)

Fixes
  - MBAR estimator now correctly passes max_iterations to pymbar.MBAR. (PR #162)
  - docs (PR #157)
  - visualisation.df_state.plot_dF_state() now correctly raises ValueError instead
    of NameError when incorrect orientation keyword argument is supplied


08/01/2021 xiki-tempula, orbeckst

  * 0.5.0

Changes
  - alchemlyb adopts NEP29
    https://numpy.org/neps/nep-0029-deprecation_policy.html
    to effectively only support the last 2-3 minor Python versions
  - Removed support for Python 2.7 and 3.6 (issue #130, #140):
    supported/tested Python versions are 3.7, 3.8, 3.9 on
    Linux, macOS, and Windows
  - The scipy constant for gas constant is used for parsers instead of the
    constants used by the corresponding MD engine (issue #125, PR #129).
    This leads to small changes in results from GROMACS simulations in kT
    compared to the previous releases, with a relative difference on the order
    of 1e-7.
  - Added unit-awareness: the base unit remains kT but dataframes need to
    carry the unit and temperature in a DataFrame.attrs so that dataframes
    can be easily converted to different energy units (issue #125)
  - The parser outputs dataframe with metadata (issue #125, PR #129).
  - Visualisation module will change the data according to input unit
    (issue #125, PR #129).
  - Bump the minimum pandas version to 1.2 (issue #130, #140).

Enhancements
  - postprocessors.units module for unit conversion (issue #125, PR #129).
  - pass_attrs decorator for safely passing variable (issue #125, PR #129).
  - alchemlyb.concat added to replace pd.concat (issue #125, PR #129).

Fixes
  - `alchemlyb.concat()` should raise ValueError when given empty list, to be
    compatible with pandas.concat() (issue #150, PR #152).
  - Fix the support for pandas >= 1.3 by skipping 1.3.0 (issue #147, PR #148).
  - Fix separate_dhdl not work for multiple columns (issue #149, PR #151).


06/08/2021 orbeckst

  * 0.4.2

Fixes
  - added back documentation that was lost in 0.4.1 release (#136)


06/01/2021 xiki-tempula, orbeckst

  * 0.4.1

Enhancements

Deprecations
  - Last release that supports Python 3.5 and 2.7.

Fixes
  - The plotting function assumes that the default unit is kcal/mol where it is
    kT (issue #124, PR #123).
  - invalid escape sequence in plotting annotations (issue #133)

Changes


04/27/2021 wehs7661, dotsdl, xiki-tempula, orbeckst

  * 0.4.0

Enhancements
  - Allow the dhdl from TI estimator to be separated for multiple lambda
    (PR #121).
  - Allow the convergence to be plotted. (PR #121)
  - Allow automatic sorting and duplication removal during subsampling
    (issue #118, PR #119).
  - Allow statistical_inefficiency to work on multiindex series. (issue #116,
    PR #117)
  - Allow the overlap matrix of the MBAR estimator to be plotted. (issue #73,
    PR #107)
  - Allow the dhdl of the TI estimator to be plotted. (issue #73, PR #110)
  - Allow the dF states to be plotted. (issue #73, PR #112)

Deprecations
  - Last version that is tested against Python 3.5 and 2.7.

Fixes
  - removed redundant statistical inefficiency calculation in
    `alchemlyb.preprocessing.subsampling.equilibrium_detection`

Changes


01/16/2020 dotsdl, orbeckst

  * 0.3.1

Enhancements

Deprecations

Fixes
  - added explicit `return_theta=True` for call to pymbar.MBAR.getFreeEnergyDifferences,
    as this was happening prior to changes in `pymbar` without the explicit call

Changes


08/05/2019 dotsdl, orbeckst, shuail, trje3733, brycestx, harlor, vtlim, lee212

  * 0.3.0

Enhancements
  - Amber TI parser (#10)
  - Amber FEP (MBAR) parser (#42)
  - Gromacs extended ensemble parser (#14)
  - NAMD FEP parser (#7, #75)
  - BAR estimator (#40)
  - enhanced performance of Gromacs parsers with pandas.read_csv() (#81)
  - GOMC TI and FEP parser (#77)

Deprecations

Fixes
  - fixed TI estimator (PR #61)
  - correctly use pV and U in the Gromacs parser (#59)

Changes
  - defaults for statistical_inefficiency() are more conservative (#39)
  - API Proposal was upgraded to API Principles (and updated)

(Note: release number 0.2.x was skipped.)


05/27/2017 dotsdl, ianmkenney, orbeckst

  * 0.1.0

First release

Features:

    - Parsers for GROMACS, including reduced potentials and gradients.
    - Subsampler functions for slicing, statitistical inefficiency, equilibration detection.
    - Minimally functional estimators for MBAR, TI.
    - high test coverage (works with data in alchemistry/alchemtests)