v0.3.0 API changes for OpenMMTools compatibility

.codecov.yml

@@ -30,10 +30,6 @@ ignore:
   - setup.py
   - blues/tests/*
   - blues/_version.py
-  - blues/*dart.py
-  - blues/switching.py
-  - blues/formats.py
-  - blues/example.py
 
 
 

.readthedocs.yml

@@ -3,7 +3,7 @@ conda:
     file: docs/environment.yml
 
 python:
-    version: 3.5
+    version: 3.6
     setup_py_install: true
     extra_requirements:
     - tests

.travis.yml

@@ -35,11 +35,6 @@ matrix:
     #      - CONDA_PY="37"
     #      - PYTHON_VER="3.7"
 
-    - os: linux
-      python: 3.5
-      env:
-          - CONDA_PY="35"
-          - PYTHON_VER="3.5"
     - os: linux
       python: 3.6
       env:
@@ -51,7 +46,6 @@ matrix:
           - CONDA_PY="37"
           - PYTHON_VER="3.7"
 
-
 before_install:
   # Additional info about the build
   - uname -a
@@ -61,8 +55,8 @@ before_install:
   - python -V
 
   # Unpack encrypted OpenEye license file
-  - if [ "$TRAVIS_SECURE_ENV_VARS" == true ]; then openssl aes-256-cbc -K $encrypted_7751cf1f2f9d_key -iv $encrypted_7751cf1f2f9d_iv -in oe_license.txt.enc -out oe_license.txt -d; fi
-  - if [ "$TRAVIS_SECURE_ENV_VARS" == false ]; then echo "OpenEye license will not be installed in forks."; fi
+  #- if [ "$TRAVIS_SECURE_ENV_VARS" == true ]; then openssl aes-256-cbc -K $encrypted_7751cf1f2f9d_key -iv $encrypted_7751cf1f2f9d_iv -in oe_license.txt.enc -out oe_license.txt -d; fi
+  #- if [ "$TRAVIS_SECURE_ENV_VARS" == false ]; then echo "OpenEye license will not be installed in forks."; fi
 
   - conda update --yes -q conda
   # Turn on always yes
@@ -80,20 +74,17 @@ install:
   - echo ${PYTHON_VER} ${CONDA_PY}
   - conda create -n ${CONDA_ENV} python=${PYTHON_VER} pip pytest pytest-cov conda-verify
   - conda activate ${CONDA_ENV}
+
     # Install pip only modules
   - pip install codecov
 
-
   # Install OpenEye dependencies
   #  Use beta version for partial bond orders
-  - conda install -c openeye/label/beta openeye-toolkits && python -c "import openeye; print(openeye.__version__)"
-  - conda install -q -c openeye/label/Orion -c omnia oeommtools packmol
-  - conda info oeommtools
-  - conda info numexpr=2.6.6
+  #- conda install -c openeye/label/beta openeye-toolkits && python -c "import openeye; print(openeye.__version__)"
+    #- conda install -q -c openeye/label/Orion -c omnia oeommtools packmol
 
   # Build and install package
   - conda build -q --python=${PYTHON_VER} devtools/conda-recipe
-  - conda info blues
   - conda install --use-local -q ${PKG_NAME}
   - conda list
 

README.md

@@ -5,28 +5,29 @@ This package takes advantage of non-equilibrium candidate Monte Carlo moves (NCM
 
 Latest release:
 [![Build Status](https://travis-ci.org/MobleyLab/blues.svg?branch=master)](https://travis-ci.org/MobleyLab/blues)
-[![Documentation Status](https://readthedocs.org/projects/mobleylab-blues/badge/?version=stable)](https://mobleylab-blues.readthedocs.io/en/stable/?badge=stable)
+[![Documentation Status](https://readthedocs.org/projects/mobleylab-blues/badge/?version=master)](https://mobleylab-blues.readthedocs.io/en/stable/?badge=master)
 [![codecov](https://codecov.io/gh/MobleyLab/blues/branch/master/graph/badge.svg)](https://codecov.io/gh/MobleyLab/blues)
 [![Anaconda-Server Badge](https://anaconda.org/mobleylab/blues/badges/version.svg)](https://anaconda.org/mobleylab/blues)
  [![DOI](https://zenodo.org/badge/62096511.svg)](https://zenodo.org/badge/latestdoi/62096511)
 
+
 ## Citations
-#### Publication
+#### Publications
 - [Gill, S; Lim, N. M.; Grinaway, P.; Rustenburg, A. S.; Fass, J.; Ross, G.; Chodera, J. D.; Mobley, D. L. “Binding Modes of Ligands Using Enhanced Sampling (BLUES): Rapid Decorrelation of Ligand Binding Modes Using Nonequilibrium Candidate Monte Carlo”](https://pubs.acs.org/doi/abs/10.1021/acs.jpcb.7b11820) - Journal of Physical Chemistry B. February 27, 2018
+- [Burley, K. H., Gill, S. C., Lim, N. M., & Mobley, D. L. "Enhancing Sidechain Rotamer Sampling Using Non-Equilibrium Candidate Monte Carlo"](https://pubs.acs.org/doi/abs/10.1021/acs.jctc.8b01018) - Journal of Chemical Theory and Computation. January 24, 2019
 
 #### Preprints
 - [BLUES v1](https://chemrxiv.org/articles/Binding_Modes_of_Ligands_Using_Enhanced_Sampling_BLUES_Rapid_Decorrelation_of_Ligand_Binding_Modes_Using_Nonequilibrium_Candidate_Monte_Carlo/5406907) - ChemRxiv September 19, 2017
 - [BLUES v2](https://doi.org/10.26434/chemrxiv.5406907.v2) - ChemRxiv September 25, 2017
 
 ## Manifest
 * `blues/` -  Source code and example scripts for BLUES toolkit
-* `devdocs/` - Class diagrams for developers
 * `devtools/` - Developer tools and documentation for conda, travis, and issuing a release
+* `docs/` - Documentation
 * `images/` - Images/logo for repository
-* `notebooks` - Jupyter notebooks for testing/development
 
 ## Prerequisites
-BLUES is compatible with MacOSX/Linux with Python>=3.5 (blues<=1.1 still works with Python 2.7)
+BLUES is compatible with MacOSX/Linux with Python>=3.6 (blues<=1.1 still works with Python 2.7)
 Install [miniconda](http://conda.pydata.org/miniconda.html) according to your system.
 
 ## Requirements
@@ -57,7 +58,7 @@ Install from source (NOT RECOMMENDED)
 git clone [email protected]:MobleyLab/blues.git
 
 # Install some dependencies
-conda install -c omnia -c conda-forge openmmtools=0.15.0 openmm=7.2.2 numpy cython
+conda install -c omnia -c conda-forge openmmtools openmm pymbar numpy cython
 
 # Install BLUES package from the top directory
 pip install -e .
@@ -69,40 +70,61 @@ pytest -v -s
 
 ## Documentation
 For documentation on the BLUES modules see [ReadTheDocs: Modules](https://mobleylab-blues.readthedocs.io/en/latest/module_doc.html)
-For a tutorial on how to use BLUES see [ReadTheDocs: Tutorial](https://mobleylab-blues.readthedocs.io/en/latest/tutorial.html)
 
-### BLUES using NCMC
-This package takes advantage of non-equilibrium candidate Monte Carlo moves (NCMC) to help sample between different ligand binding modes using the OpenMM simulation package.  One goal for this package is to allow for easy additions of other moves of interest, which will be covered below.
+### Usage
+This package takes advantage of non-equilibrium candidate Monte Carlo moves (NCMC) to help sample between different ligand binding modes using the OpenMM simulation package. One goal for this package is to allow for easy additions of other moves of interest, which will be covered below.
+
+The integrator of `BLUES` contains the framework necessary for NCMC. Specifically, the integrator class calculates the work done during a NCMC move. It also controls the lambda scaling of parameters. The integrator that BLUES uses inherits from `openmmtools.integrators.AlchemicalNonequilibriumLangevinIntegrator` to keep track of the work done outside integration steps, allowing Monte Carlo (MC) moves to be incorporated together with the NCMC thermodynamic perturbation protocol. Currently, the `openmmtools.alchemy` package is used to generate the lambda parameters for the ligand, allowing alchemical modification of the sterics and electrostatics of the system.
+
+The `BLUESSampler` class in `ncmc.py` serves as a wrapper for running NCMC+MD simulations. To run the hybrid simulation, the `BLUESSampler` class requires defining two moves for running the (1) MD simulation and (2) the NCMC protcol. These moves are defined in the `ncmc.py` module. A simple example is provided below.
+
+#### Example
+Using the BLUES framework requires the use of a **ThermodynamicState** and **SamplerState** from `openmmtools` which we import from `openmmtools.states`:
 
-### Example Use
-An example of how to set up a simulation sampling the binding modes of toluene bound to T4 lysozyme using NCMC and a rotational move can be found in `examples/example_rotmove.py`
+```python
+from openmmtools.states import ThermodynamicState, SamplerState
+from openmmtools.testsystems import TolueneVacuum
+from blues.ncmc import *
+from simtk import unit
+```
 
-### Actually using BLUES
-The integrator of `BLUES` contains the framework necessary for NCMC.  Specifically, the integrator class calculates the work done during a NCMC move. It also controls the lambda scaling of parameters. The integrator that BLUES uses inherits from `openmmtools.integrators.AlchemicalNonequilibriumLangevinIntegrator` to keep track of the work done outside integration steps, allowing Monte Carlo (MC) moves to be incorporated together with the NCMC thermodynamic perturbation protocol. Currently the `openmmtools.alchemy` package is used to generate the lambda parameters for the ligand, allowing alchemical modification of the sterics and electrostatics of the system.
-The `Simulation` class in `blues/simulation.py` serves as a wrapper for running NCMC simulations.
+Create the states for a toluene molecule in vacuum.
+```python
+tol = TolueneVacuum()
+thermodynamic_state = ThermodynamicState(tol.system, temperature=300*unit.kelvin)
+sampler_state = SamplerState(positions=tol.positions)
+```
 
-### Implementing Custom Moves
-Users can implement their own MC moves into NCMC by inheriting from an appropriate `blues.moves.Move` class and constructing a custom `move()` method that only takes in an Openmm context object as a parameter. The `move()` method will then access the positions of that context, change those positions, then update the positions of that context. For example if you would like to add a move that randomly translates a set of coordinates the code would look similar to this pseudocode:
+Define our langevin dynamics move for the MD simulation portion and then our NCMC move which performs a random rotation. Here, we use a customized LangevinDynamicsMove which allows us to store information from the MD simulation portion.
 
 ```python
-from blues.moves import Move
-class TranslationMove(Move):
-   	def __init__(self, atom_indices):
-   		self.atom_indices = atom_indices
-   	def move(context):
-   	"""pseudocode for move"""
-   		positions = context.context.getState(getPositions=True).getPositions(asNumpy=True)
-   		#get positions from context
-   		#use some function that translates atom_indices
-   		newPositions = RandomTranslation(positions[self.atom_indices])
-   		context.setPositions(newPositions)
-   		return context
+dynamics_move = ReportLangevinDynamicsMove(n_steps=10)
+ncmc_move = RandomLigandRotationMove(n_steps=10, atom_subset=list(range(15)))
 ```
 
-### Combining Moves
-**Note: This feature has not been tested, use at your own risk.**
-If you're interested in combining moves together sequentially–say you'd like to perform a rotation and translation move together–instead of coding up a new `Move` class that performs that, you can instead leverage the functionality of existing `Move`s using the `CombinationMove` class. `CombinationMove` takes in a list of instantiated `Move` objects. The `CombinationMove`'s `move()` method perfroms the moves in either listed or reverse order. Replicating a rotation and translation move on t, then, can effectively be done by passing in an instantiated TranslationMove (from the pseudocode example above) and RandomLigandRotation.
-One important non-obvious thing to note about the CombinationMove class is that to ensure detailed balance is maintained, moves are done half the time in listed order and half the time in the reverse order.
+Provide the `BLUESSampler` class with an `openmm.Topology` and these objects to run the NCMC+MD simulation.
+```python
+sampler = BLUESSampler(thermodynamic_state=thermodynamic_state,
+                      sampler_state=sampler_state,
+                      dynamics_move=dynamics_move,
+                      ncmc_move=ncmc_move,
+                      topology=tol.topology)
+sampler.run(n_iterations=1)
+```
+
+### Implementing custom NCMC moves
+Users can implement their own MC moves into NCMC by inheriting from an appropriate `blues.ncmc.NCMCMove` class and overriding the `_propose_positions()` method that only takes in and returns a positions array.
+Updating the positions in the context is handled by the `BLUESSampler` class.
+
+With blues>=0.2.5, the API has been redesigned to allow compatibility with moves implemented in [`openmmtools.mcmc`](https://openmmtools.readthedocs.io/en/0.18.1/mcmc.html#mcmc-move-types). Users can take MCMC moves and turn them into NCMC moves without having to write new code. Simply, override the `_get_integrator()` method to use the `blues.integrator.AlchemicalExternalLangevinIntegrator` provided in this module. For example:
+
+```python
+from blues.ncmc import NCMCMove
+from openmmtools.mcmc import MCDisplacementMove
+class NCMCDisplacementMove(MCDisplacementMove, NCMCMove):
+    def _get_integrator(self, thermodynamic_state):
+        return NCMCMove._get_integrator(self,thermodynamic_state)
+```
 
 ## Versions:
 - Version 0.0.1: Basic BLUES functionality/package
@@ -116,7 +138,9 @@ One important non-obvious thing to note about the CombinationMove class is that
 - [Version 0.2.0](https://doi.org/10.5281/zenodo.1284568): YAML support, API changes, custom reporters.
 - [Version 0.2.1](https://doi.org/10.5281/zenodo.1288925): Bug fix in alchemical correction term
 - [Version 0.2.2](https://doi.org/10.5281/zenodo.1324415): Bug fixes for OpenEye tests and restarting from the YAML; enhancements to the Logger and package installation.
-- [Version 0.2.3](https://zenodo.org/badge/latestdoi/62096511): Improvements to Travis CI, fix in velocity synicng, and add tests for checking freezing selection.
+- [Version 0.2.3](https://doi.org/10.5281/zenodo.1409272): Improvements to Travis CI, fix in velocity synicng, and add tests for checking freezing selection.
+- [Version 0.2.4](https://doi.org/10.5281/zenodo.2672932): Addition of a simple test that can run on CPU.
+- [Version 0.2.5](): API redesign for compatibility with `openmmtools`
 
 ## Acknowledgements
 We would like to thank Patrick Grinaway and John Chodera for their basic code framework for NCMC in OpenMM (see https://github.com/choderalab/perses/tree/master/perses/annihilation), and John Chodera and Christopher Bayly for their helpful discussions.

blues/__init__.py

@@ -2,9 +2,6 @@
 """
 BLUES
 """
-# Add imports here
-from blues import integrators, moves, reporters, settings, simulation, utils
-
 # Handle versioneer
 from ._version import get_versions
 versions = get_versions()