ABFE testfiles (#41)

* Add ABFE test files obtained from the tutorial http://www.alchemistry.org/wiki/Absolute_Binding_Free_Energy_-_Gromacs_2016.
* ABFE test
* update doc
* Include xvg as well

.gitignore

@@ -0,0 +1,5 @@
+docs/_build
+src/alchemtest.egg-info
+*__pycache__*
+.idea
+*.DS_Store

MANIFEST.in

@@ -1,5 +1,5 @@
 include *.rst
-recursive-include src/alchemtest *.gz *.bz2 *.zip *.rst *.txt *.out
+recursive-include src/alchemtest *.gz *.bz2 *.zip *.rst *.txt *.out *.xvg
 include README.rst
 include LICENSE
 include versioneer.py

docs/gmx.rst

@@ -14,6 +14,7 @@ can be accessed using the following accessor functions:
 .. autosummary::
 
    load_benzene
+   load_ABFE
    load_expanded_ensemble_case_1
    load_expanded_ensemble_case_2
    load_expanded_ensemble_case_3
@@ -75,4 +76,20 @@ one does not contain a energy column.
 
 .. autofunction:: alchemtest.gmx.load_water_particle_with_total_energy
 .. autofunction:: alchemtest.gmx.load_water_particle_with_potential_energy
-.. autofunction:: alchemtest.gmx.load_water_particle_without_energy
+.. autofunction:: alchemtest.gmx.load_water_particle_without_energy
+
+---------------------------------------------------------------------
+Absolute Binding Free Energy of n-phenylglycinonitrile to T4 lysozyme
+---------------------------------------------------------------------
+
+The dataset for computing the absolute binding free energy of
+n-phenylglycinonitrile to T4 lysozyme. The calculation has two legs: complex
+and ligand. In the complex leg, restraint is applied to the ligand and the
+coulombic as well as the Van der Waals interactions are decoupled sequentially.
+In the ligand leg, only the coulombic and Van der Waals interactions are
+decoupled.
+
+
+.. include:: ../src/alchemtest/gmx/ABFE/descr.rst
+
+.. autofunction:: alchemtest.gmx.load_ABFE

src/alchemtest/gmx/ABFE/descr.rst

@@ -0,0 +1,41 @@
+Gromacs: n-phenylglycinonitrile in T4 lysozyme
+==============================================
+
+Obtain the absolute binding free energy of the n-phenylglycinonitrile
+for T4 lysozyme by alchemically turning n-phenylglycinonitrile in T4 lysozyme
+and water into vacuum.
+
+Notes
+-----
+Data Set Characteristics:
+    :Number of Legs: 2 (Restraint, Coulomb, VDW for protein;
+        Coulomb, VDW for water)
+    :Number of Windows: 11 for Restraint, 5 for Coulomb, 16 for VDW
+    :Length of Windows: 1ns for protein and 5ns for water
+    :System Size: 33005 atoms for protein and 2103 atoms for water
+    :Temperature: 300 K
+    :Pressure: 1 bar
+    :Alchemical Pathway: vdw + coul --> restraint + vdw + coul -->
+        restraint + vdw --> restraint + vacuum
+    :Reference Hydration Free Energy in protein: -21.721  +-  0.089 kcal/mol
+    :Reference Hydration Free Energy in water: -7.679  +-  0.080 kcal/mol
+    :Missing Values: None
+    :Energy unit: kJ/mol
+    :Time unit: ps
+    :Creator: \Z. Wu
+    :Donor: Zhiyi Wu ([email protected])
+    :Date: March 2021
+    :License: `CC0
+	      <https://creativecommons.org/publicdomain/zero/1.0/>`_
+	      Public Domain Dedication
+
+This dataset was generated using
+`tutorial <http://www.alchemistry.org/wiki/Absolute_Binding_Free_Energy_-_Gromacs_2016>`_
+, with the `Gromacs <http://www.gromacs.org/>`_ molecular dynamics engine.
+
+Data sourced from [Boyce2009]_.
+
+.. [Boyce2009] Boyce, S.E., Mobley, D.L., Rocklin, G.J., Graves, A.P., Dill,
+    K.A., Shoichet, B.K. (2009) Predicting Ligand Binding Affinity with
+    Alchemical Free Energy Methods in a Polar Model Binding Site. J. Mol. Biol.
+    394, 747–7636

src/alchemtest/gmx/__init__.py

@@ -3,7 +3,8 @@
 """
 
 from .access import load_benzene
-from .access import (load_benzene, load_expanded_ensemble_case_1,
+from .access import (load_benzene, load_ABFE,
+                     load_expanded_ensemble_case_1,
                      load_expanded_ensemble_case_2,
                      load_expanded_ensemble_case_3,
                      load_water_particle_with_potential_energy,

src/alchemtest/gmx/access.py

@@ -31,6 +31,30 @@ def load_benzene():
     return Bunch(data=data,
                  DESCR=fdescr)
 
+def load_ABFE():
+    """Load the Gromacs ABFE dataset.
+
+    Returns
+    -------
+    data : Bunch
+        Dictionary-like object, the interesting attributes are:
+
+        - 'data' : the data files by alchemical leg
+        - 'DESCR': the full description of the dataset
+
+    """
+
+    module_path = dirname(__file__)
+
+    data = {'complex': sorted(glob(join(module_path, 'ABFE', 'complex', 'dhdl_*.xvg'))),
+            'ligand': sorted(glob(join(module_path, 'ABFE', 'ligand', 'dhdl_*.xvg')))}
+
+    with open(join(module_path, 'ABFE', 'descr.rst')) as rst_file:
+        fdescr = rst_file.read()
+
+    return Bunch(data=data,
+                 DESCR=fdescr)
+
 def load_expanded_ensemble_case_1():
     """Load the Gromacs Host CB7 Guest C3 expanded ensemble dataset, case 1 (single simulation visits all states).