Merge pull request #3 from openmm/master

Sync with official repo

.travis.yml

@@ -75,7 +75,7 @@ matrix:
 
     - sudo: false
       dist: trusty
-      python: 2.7_with_system_site_packages
+      python: 3.6
       env: ==STATIC_LIB==
            OPENCL=false
            CUDA=false
@@ -85,8 +85,8 @@ matrix:
 
     - sudo: false
       dist: trusty
-      python: 2.7_with_system_site_packages
-      env: ==PYTHON_2==
+      python: 3.6
+      env: ==PYTHON_3_6==
            OPENCL=false
            CUDA=false
            CC=$CCACHE/clang
@@ -95,9 +95,9 @@ matrix:
            CMAKE_FLAGS="-DOPENMM_GENERATE_API_DOCS=ON"
 
     - sudo: false
-      dist: trusty
-      python: 3.4
-      env: ==PYTHON_3==
+      dist: xenial
+      python: 3.8
+      env: ==PYTHON_3_8==
            OPENCL=false
            CUDA=false
            CC=$CCACHE/gcc

CMakeLists.txt

@@ -157,7 +157,7 @@ ENDIF (NOT CMAKE_CXX_FLAGS_RELEASE)
 
 SET(OPENMM_LIBRARY_NAME OpenMM)
 SET(OPENMM_MAJOR_VERSION 7)
-SET(OPENMM_MINOR_VERSION 4)
+SET(OPENMM_MINOR_VERSION 5)
 SET(OPENMM_BUILD_VERSION 0)
 
 ADD_DEFINITIONS(-DOPENMM_LIBRARY_NAME=${OPENMM_LIBRARY_NAME}

CONTRIBUTING.md

+## How to Contribute to OpenMM Development
+
+We welcome anyone who wants to contribute to the project, whether by adding a feature,
+fixing a bug, or improving documentation.  The process is quite simple.
+
+First, it is always best to begin by opening an issue on Github that describes the change you
+want to make.  This gives everyone a chance to discuss it before you put in a lot of work.
+For bug fixes, we will confirm that the behavior is actually a bug and that the proposed fix
+is correct.  For new features, we will decide whether the proposed feature is something we
+want and discuss possible designs for it.
+
+Once everyone is in agreement, the next step is to
+[create a pull request](https://help.github.com/en/articles/about-pull-requests) with the code changes.
+For larger features, feel free to create the pull request even before the implementaton is
+finished so as to get early feedback on the code.  When doing this, put the letters "WIP" at
+the start of the title of the pull request to indicate it is still a work in progress.
+
+For new features, consult the [New Feature Checklist](https://github.com/openmm/openmm/wiki/Checklist-when-adding-a-new-feature),
+which lists various items that need to be included before the feature can be merged (documentation,
+tests, serialization, support for all APIs, etc.).  Not every item is necessarily applicable to
+every new feature, but usually at least some of them are.
+
+The core developers will review the pull request and may suggest changes.  Simply push the
+changes to the branch that is being pulled from, and they will automatically be added to the
+pull request.  In addition, the full test suite is automatically run on every pull request,
+and rerun every time a change is added.  Once the tests are passing and everyone is satisfied
+with the code, the pull request will be merged.  Congratulations on a succesful contribution!
\ No newline at end of file

README.md

-[![Build Status](https://travis-ci.org/pandegroup/openmm.svg?branch=master)](https://travis-ci.org/pandegroup/openmm?branch=master)
+[![Build Status](https://travis-ci.org/openmm/openmm.svg?branch=master)](https://travis-ci.org/openmm/openmm?branch=master)
 [![Anaconda Cloud Badge](https://anaconda.org/omnia/openmm/badges/downloads.svg)](https://anaconda.org/omnia/openmm)
 
 ## OpenMM: A High Performance Molecular Dynamics Library

SUPPORT.md

+## How to Get Support for OpenMM
+
+There are two main venues for getting support for OpenMM: the [discussion forum](https://simtk.org/forums/viewforum.php?f=161)
+and the [Github repository](https://github.com/openmm/openmm).  There is some overlap
+between the two, but generally speaking the forum is for user oriented issues while the
+repository is for developer oriented issues.  If you have a question about how to use OpenMM
+(including writing programs that access it through its public API), post on the forum.  If
+you want to suggest a change to the code, or if you think you have found a bug,
+open an issue on Github.  The core developers monitor both, so don't worry if you aren't
+sure which one is most appropriate for your question.  We will see it either way.
+
+You also may want to consult the [documentation](http://docs.openmm.org/).  It is quite
+thorough, and you may be able to find the answer to your question.
\ No newline at end of file

appveyor.yml

-os: Visual Studio 2015
+os: Visual Studio 2019
 platform: x64
 configuration: Release
 shallow_clone: true
 install:
 
 # Setup shell for VS2015, x64
-  - call "c:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64
+  - call "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64
 # Set path to python, git-bash tools.
   - "set PATH=C:\\Python35-x64;C:\\Python35-x64\\Scripts;%PATH%"
   - "set PATH=C:\\Program Files (x86)\\Git\\bin;%PATH%"
@@ -20,7 +20,7 @@ install:
   - "set CCLASH_DIR=C:\\ProgramData\\cclash"
 
 # Download FFTW3 for PME plugin
-  - C:\MinGW\msys\1.0\bin\wget -q ftp://ftp.fftw.org/pub/fftw/fftw-3.3.4-dll64.zip
+  - ps: Invoke-WebRequest ftp://ftp.fftw.org/pub/fftw/fftw-3.3.4-dll64.zip -OutFile fftw-3.3.4-dll64.zip
   - 7z x fftw-3.3.4-dll64.zip -oC:\fftw > null
   - cd C:\fftw
   - lib /def:libfftw3f-3.def
@@ -28,7 +28,7 @@ install:
   - "set PATH=C:\\fftw;%PATH%"
 
 # Download and install some OpenMM build dependencies (doxygen, swig)
-  - choco install -y doxygen.portable swig > null
+  - choco install -y doxygen.install swig > null
 
 # Download OpenCL Headers and build the ICD loader
   - ps: "[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12;"

devtools/Jenkinsfile

 pipeline {
-    agent any
+    agent none
 
     stages {
         stage("Build and test") {
             parallel {
                 stage("Build and test CUDA platform") {
-                    agent { label "cuda" }
+                    agent {
+                        docker {
+                            image "swails/openmm-all:latest"
+                            label "cuda && docker"
+                            alwaysPull true
+                        }
+                    }
                     steps {
-                        sh '''#!/bin/bash -lex
-                            git clean -fxd && git checkout .
-                            env
-                            module load cuda conda
-                            export OPENMM_CUDA_COMPILER=`which nvcc`
-                            bash -e devtools/ci/jenkins/install.sh
-                            bash -e devtools/ci/jenkins/test.sh -R 'TestCuda' --parallel 2
-                        '''
+                        sh "git clean -fxd && git checkout ."
+                        withEnv(["OPENMM_CUDA_COMPILER=/usr/local/cuda/bin/nvcc"]) {
+                            sh "devtools/ci/jenkins/install.sh"
+                            sh "devtools/ci/jenkins/test.sh -R 'TestCuda' --parallel 2"
+                        }
                     }
                 }
 
                 stage("Build and test OpenCL platform") {
-                    agent { label "cuda" }
+                    agent {
+                        docker {
+                            image "swails/openmm-all:latest"
+                            label "cuda && docker"
+                            alwaysPull true
+                        }
+                    }
                     steps {
-                        sh '''#!/bin/bash -lex
-                            git clean -fxd && git checkout .
-                            env
-                            module load cuda conda
-                            export OPENMM_CUDA_COMPILER=`which nvcc`
-                            bash -e devtools/ci/jenkins/install.sh
-                            bash -e devtools/ci/jenkins/test.sh -R 'TestOpenCL' --parallel 2
-                        '''
+                        sh "git clean -fxd && git checkout ."
+                        sh "devtools/ci/jenkins/install.sh"
+                        sh "devtools/ci/jenkins/test.sh -R 'TestOpenCL' --parallel 2"
                     }
                 }
 
                 stage("Build/test CPU platforms") {
                     agent {
-                        dockerfile {
-                            dir "devtools/ci/jenkins"
+                        docker {
+                            image "swails/openmm-cpu:latest"
                             label "docker"
+                            alwaysPull true
                         }
                     }
 
                     steps {
-                        sh '''#!/bin/bash -lex
-                        git clean -fxd && git checkout .
-                        bash -e devtools/ci/jenkins/install_and_test_cpu.sh
-                        '''
+                        sh "git clean -fxd && git checkout ."
+                        sh "devtools/ci/jenkins/install_and_test_cpu.sh"
+                    }
                 }
             }
-            } // parallel
         }
     }
 }

devtools/ci/jenkins/Dockerfile

-FROM ubuntu:xenial
-
-ENV PATH="/opt/miniconda/bin:${PATH}"
-
-RUN apt-get update && \
-    apt-get install -y wget git gromacs doxygen gfortran libfftw3-dev gcc g++ bzip2 automake make lsb-core && \
-    wget https://repo.continuum.io/miniconda/Miniconda3-4.5.11-Linux-x86_64.sh -O miniconda.sh && \
-    bash miniconda.sh -b -p "/opt/miniconda" && \
-    rm -f miniconda.sh && \
-    mkdir /.conda &&  chmod -R 777 /.conda &&  chmod -R 777 /opt/miniconda && \
-    conda install -y cmake numpy scipy pytest swig cython

devtools/ci/jenkins/install.sh

+#!/bin/bash -ex
 # This script is executed via the line:
 #   source devtools/ci/jenkins/install.sh
 # in a bash shell with the -lex options turned on
@@ -14,7 +15,7 @@ g++ --version
 if [ ! -z "$OPENMM_CUDA_COMPILER" ]; then
     echo "Using nvcc ($OPENMM_CUDA_COMPILER) version:"
     $OPENMM_CUDA_COMPILER --version
-    CUDA_ARGS="-DCUDA_TOOLKIT_ROOT_DIR=${CUDA_HOME}"
+    CUDA_ARGS="-DCUDA_TOOLKIT_ROOT_DIR=${CUDA_HOME} -DOPENMM_BUILD_CUDA_LIB=true"
 fi
 
 cmake -DCMAKE_INSTALL_PREFIX="`pwd`/install" -DCMAKE_CXX_COMPILER=g++ -DCMAKE_C_COMPILER=gcc \

devtools/ci/jenkins/install_and_test_cpu.sh

-#!/bin/bash
+#!/bin/bash -ex
 
 EXTRA_CMAKE_ARGS="-DOPENMM_BUILD_CUDA_LIB=false -DOPENMM_BUILD_OPENCL_LIB=false"
 . devtools/ci/jenkins/install.sh

devtools/ci/jenkins/test.sh

-#!/bin/sh
+#!/bin/bash -ex
 
 python devtools/run-ctest.py --job-duration=120 --timeout 300 --in-order $*
\ No newline at end of file

devtools/forcefield-scripts/processCharmmForceField.py

@@ -377,7 +377,7 @@ for values in sorted(uniqueCmaps, key=lambda x: uniqueCmaps[x]):
 for map in cmaps:
     print('   <Torsion map="%d" class1="%s" class2="%s" class3="%s" class4="%s" class5="%s"/>' % (uniqueCmaps[map.values], map.classes[0], map.classes[1], map.classes[2], map.classes[3], map.classes[4]))
 print(' </CMAPTorsionForce>')
-print(' <NonbondedForce coulomb14scale="1.0" lj14scale="1.0">')
+print(' <NonbondedForce coulomb14scale="1.0" lj14scale="1.0" useDispersionCorrection="False">')
 for type in atomTypes:
     print('  <Atom type="%d" charge="%g" sigma="1.0" epsilon="1.0"/>' % (type.type, type.charge))
 print(' </NonbondedForce>')
@@ -464,6 +464,7 @@ print("""]
 
 customNonbondedForce = mm.CustomNonbondedForce('4*eps*((sig/r)^12-(sig/r)^6); eps=epsilon(type1, type2); sig=sigma(type1, type2)')
 customNonbondedForce.setNonbondedMethod(min(nonbondedForce.getNonbondedMethod(), 2))
+customNonbondedForce.setUseLongRangeCorrection(False)
 customNonbondedForce.addTabulatedFunction('epsilon', mm.Discrete2DFunction(numAtomClasses, numAtomClasses, epsilon))
 customNonbondedForce.addTabulatedFunction('sigma', mm.Discrete2DFunction(numAtomClasses, numAtomClasses, sigma))
 customNonbondedForce.addPerParticleParameter('type')

devtools/packaging/scripts/windows/Vagrantfile

 Vagrant.configure("2") do |config|
-  config.vm.box = "gusztavvargadr/windows10ee"
+  config.vm.box = "gusztavvargadr/windows-10"
   config.vm.provision :shell, path: "prepare.ps1"
 
   config.vm.provider :virtualbox do |vb|

devtools/packaging/scripts/windows/prepare.ps1

@@ -2,8 +2,8 @@ cd C:\Users\vagrant
 
 # Install CUDA.
 
-wget https://developer.nvidia.com/compute/cuda/9.2/Prod2/network_installers/cuda_9.2.148_win10_network -UseBasicParsing -OutFile cuda_9.2.148_win10_network.exe
-.\cuda_9.2.148_win10_network.exe -s nvcc_9.2 cudart_9.2 cufft_9.2 cufft_dev_9.2 nvrtc_9.2 nvrtc_dev_9.2 | Out-Null
+wget https://developer.nvidia.com/compute/cuda/10.1/Prod/network_installers/cuda_10.1.168_win10_network.exe -UseBasicParsing -OutFile cuda_10.1.168_win10_network.exe
+.\cuda_10.1.168_win10_network.exe -s nvcc_10.1 cudart_10.1 cufft_10.1 cufft_dev_10.1 nvrtc_10.1 nvrtc_dev_10.1 | Out-Null
 
 # Install AMD APP SDK.
 
@@ -14,10 +14,11 @@ wget https://s3.amazonaws.com/omnia-ci/AMD-APP-SDK-v2.9-1.599.381-GA-Full-window
 
 wget https://repo.continuum.io/miniconda/Miniconda3-latest-Windows-x86_64.exe -UseBasicParsing -OutFile Miniconda3-latest-Windows-x86_64.exe
 .\Miniconda3-latest-Windows-x86_64.exe /S /D=C:\Miniconda3 | Out-Null
+[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\Miniconda3;C:\Miniconda3\Scripts;C:\Miniconda3\Library\bin", [EnvironmentVariableTarget]::User)
 
 # Install software with conda.
 
-&"C:\Miniconda3\Scripts\conda.exe" config --add channels omnia --add channels conda-forge
+& "C:\Miniconda3\Scripts\conda.exe" config --add channels omnia --add channels conda-forge
 & "C:\Miniconda3\Scripts\conda.exe" install -y fftw3f==3.3.4=vc14_2 jinja2 lxml sphinx sphinxcontrib-autodoc_doxygen sphinxcontrib-lunrsearch conda-build anaconda-client
 & "C:\Miniconda3\Scripts\pip.exe" install sphinxcontrib.bibtex
 

docs-source/developerguide/developer.rst

@@ -319,17 +319,8 @@ other Platforms.
 
 When using the reference Platform, the “platform-specific data” stored in
 ContextImpl is of type ReferencePlatform::PlatformData, which is declared in
-ReferencePlatform.h.  Several of the fields in this class are declared as void*
-to avoid having to include SimTKOpenMMRealType.h in ReferencePlatform.h.  If you
-look in ReferenceKernels.cpp, you will find code for extracting the correct
-values of these fields.  For example:
-::
-
-    static vector<Vec3>& extractPositions(ContextImpl& context) {
-        ReferencePlatform::PlatformData* data =
-                reinterpret_cast<ReferencePlatform::PlatformData*>(context.getPlatformData());
-        return *((vector<Vec3>*) data->positions);
-    }
+ReferencePlatform.h.  It has fields for storing positions, velocities, box
+vectors, and other types of data.
 
 The PlatformData’s vector of forces contains one element for each particle.  At
 the start of each force evaluation, all elements of it are set to zero.  Each

docs-source/licenses/Licenses.txt

@@ -2,7 +2,7 @@ OpenMM was developed by Simbios, the NIH National Center for Physics-Based
 Simulation of Biological Structures at Stanford, funded under the NIH Roadmap
 for Medical Research, grant U54 GM072970. See https://simtk.org.
 
-Portions copyright � 2008-2015 Stanford University and the Authors.
+Portions copyright � 2008-2019 Stanford University and the Authors.
 
 There are several licenses which cover different parts of OpenMM as described
 below.
@@ -128,6 +128,7 @@ under the Creative Commons Attribution 3.0 Unported license.  For details, see
 https://creativecommons.org/licenses/by/3.0.  This library was modified to move
 it inside the simtk.openmm.app.internal module.
 
+
 7. irrXML
 
 OpenMM uses the irrXML library which is copyright 2002-2005 Nikolaus Gebhardt.
@@ -148,3 +149,31 @@ freely, subject to the following restrictions:
 2. Altered source versions must be plainly marked as such, and must not be
    misrepresented as being the original software.
 3. This notice may not be removed or altered from any source distribution.
+
+
+8. L-BFGS
+
+OpenMM uses the L-BFGS library by Jorge Nocedal and Naoaki Okazaki.  It may be
+used under the following license:
+
+Copyright (c) 1990, Jorge Nocedal
+Copyright (c) 2007-2010 Naoaki Okazaki
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

docs-source/usersguide/application.rst

@@ -69,7 +69,7 @@ Anaconda or Miniconda.
 
     conda install -c omnia -c conda-forge openmm
 
-This installs a version of OpenMM that is compiled to work with CUDA 9.2.
+This installs a version of OpenMM that is compiled to work with CUDA 10.1.
 Alternatively you can request a version that is compiled for a specific CUDA
 version with the command
 ::
@@ -78,7 +78,7 @@ version with the command
 
 where :code:`cuda92` should be replaced with the particular CUDA version
 installed on your computer.  Supported values are :code:`cuda75`, :code:`cuda80`,
-:code:`cuda90`, :code:`cuda91`, :code:`cuda92`, and :code:`cuda100`.  Because
+:code:`cuda90`, :code:`cuda91`, :code:`cuda92`, :code:`cuda100`, and :code:`cuda101`.  Because
 different CUDA releases are not binary compatible with each other, OpenMM can
 only work with the particular CUDA version it was compiled with.
 
@@ -120,7 +120,7 @@ steps.
         forcefield = ForceField('amber14-all.xml', 'amber14/tip3pfb.xml')
         system = forcefield.createSystem(pdb.topology, nonbondedMethod=PME,
                 nonbondedCutoff=1*nanometer, constraints=HBonds)
-        integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
+        integrator = BAOABLangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
         simulation = Simulation(pdb.topology, system, integrator)
         simulation.context.setPositions(pdb.positions)
         simulation.minimizeEnergy()
@@ -210,10 +210,10 @@ convenient and less error-prone.  We could have equivalently specified
 The units system will be described in more detail later, in Section :ref:`units-and-dimensional-analysis`.
 ::
 
-    integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
+    integrator = BAOABLangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
 
 This line creates the integrator to use for advancing the equations of motion.
-It specifies a :class:`LangevinIntegrator`, which performs Langevin dynamics,
+It specifies a :class:`BAOABLangevinIntegrator`, which performs Langevin dynamics,
 and assigns it to a variable called :code:`integrator`\ .  It also specifies
 the values of three parameters that are specific to Langevin dynamics: the
 simulation temperature (300 K), the friction coefficient (1 ps\ :sup:`-1`\ ), and
@@ -295,7 +295,7 @@ found in OpenMM’s :file:`examples` folder with the name :file:`simulateAmber.p
         inpcrd = AmberInpcrdFile('input.inpcrd')
         system = prmtop.createSystem(nonbondedMethod=PME, nonbondedCutoff=1*nanometer,
                 constraints=HBonds)
-        integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
+        integrator = BAOABLangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
         simulation = Simulation(prmtop.topology, system, integrator)
         simulation.context.setPositions(inpcrd.positions)
         if inpcrd.boxVectors is not None:
@@ -389,7 +389,7 @@ with the name :file:`simulateGromacs.py`.
                 includeDir='/usr/local/gromacs/share/gromacs/top')
         system = top.createSystem(nonbondedMethod=PME, nonbondedCutoff=1*nanometer,
                 constraints=HBonds)
-        integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
+        integrator = BAOABLangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
         simulation = Simulation(top.topology, system, integrator)
         simulation.context.setPositions(gro.positions)
         simulation.minimizeEnergy()
@@ -453,7 +453,7 @@ on the :class:`CharmmPsfFile`.
         params = CharmmParameterSet('charmm22.rtf', 'charmm22.prm')
         system = psf.createSystem(params, nonbondedMethod=NoCutoff,
                 nonbondedCutoff=1*nanometer, constraints=HBonds)
-        integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
+        integrator = BAOABLangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
         simulation = Simulation(psf.topology, system, integrator)
         simulation.context.setPositions(pdb.positions)
         simulation.minimizeEnergy()
@@ -1022,13 +1022,13 @@ Integrators
 OpenMM offers a choice of several different integration methods.  You select
 which one to use by creating an integrator object of the appropriate type.
 
-Langevin Integrator
--------------------
+BAOAB Langevin Integrator
+-------------------------
 
 In the examples of the previous sections, we used Langevin integration:
 ::
 
-    integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
+    integrator = BAOABLangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
 
 The three parameter values in this line are the simulation temperature (300 K),
 the friction coefficient (1 ps\ :sup:`-1`\ ), and the step size (0.002 ps).  You
@@ -1037,6 +1037,16 @@ on all values.  For example, the step size could be written either as
 :code:`0.002*picoseconds` or :code:`2*femtoseconds`\ .  They are exactly
 equivalent.
 
+Langevin Integrator
+-------------------
+
+:code:`LangevinIntegrator` is very similar to :code:`BAOABLangevinIntegrator`,
+but it uses a different discretization of the Langevin equation.
+:code:`BAOABLangevinIntegrator` tends to produce more accurate configurational
+sampling, and therefore is preferred for most applications.  Also note that
+:code:`LangevinIntegrator` (unlike :code:`BAOABLangevinIntegrator`) is a leapfrog
+integrator, so the velocities are offset by half a time step from the positions.
+
 Leapfrog Verlet Integrator
 --------------------------
 
@@ -1101,16 +1111,6 @@ algorithm\ :cite:`Tuckerman1992`.  This allows some forces in the system to be e
 frequently than others.  For details on how to use it, consult the API
 documentation.
 
-aMD Integrator
---------------
-
-There are three different integrator types that implement variations of the
-aMD\ :cite:`Hamelberg2007` accelerated sampling algorithm: :class:`AMDIntegrator`,
-:class:`AMDForceGroupIntegrator`, and :class:`DualAMDIntegrator`.  They
-perform integration on a modified potential energy surface to allow much faster
-sampling of conformations.  For details on how to use them, consult the API
-documentation.
-
 Compound Integrator
 -------------------
 
@@ -1155,7 +1155,7 @@ previous section:
     system = prmtop.createSystem(nonbondedMethod=PME, nonbondedCutoff=1*nanometer,
             constraints=HBonds)
     system.addForce(MonteCarloBarostat(1*bar, 300*kelvin))
-    integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
+    integrator = BAOABLangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
     ...
 
 The parameters of the Monte Carlo barostat are the pressure (1 bar) and
@@ -1371,6 +1371,55 @@ a checkpoint file every 5,000 steps, for example:
 
 Note that the checkpoint reporter will overwrite the last checkpoint file.
 
+
+Enhanced Sampling Methods
+=========================
+
+In many situations, the goal of a simulation is to sample the range of configurations
+accessible to a system.  It does not matter whether the simulation represents a
+single, physically realistic trajectory, only whether it produces a correct distribution
+of states.  In this case, a variety of methods can be used to sample configuration
+space much more quickly and efficiently than a single physical trajectory would.
+These are known as enhanced sampling methods.  OpenMM offers several that you
+can choose from.  They are briefly described here.  Consult the API documentation
+for more detailed descriptions and example code.
+
+Simulated Tempering
+-------------------
+
+Simulated tempering\ :cite:`Marinari1992` involves making frequent changes to the
+temperature of a simulation.  At high temperatures, it can quickly cross energy barriers
+and explore a wide range of configurations.  At lower temperatures, it more thoroughly
+explores each local region of configuration space.  This is a powerful method to
+speed up sampling when you do not know in advance what motions you want to sample.
+Simply specify the range of temperatures to simulate and the algorithm handles
+everything for you mostly automatically.
+
+Metadynamics
+------------
+
+Metadynamics\ :cite:`Barducci2008` is used when you do know in advance what
+motions you want to sample.  You specify one or more collective variables, and the
+algorithm adds a biasing potential to make the simulation explore a wide range of
+values for those variables.  It does this by periodically adding "bumps" to the biasing
+potential at the current values of the collective variables.  This encourages the simulation
+to move away from regions it has already explored and sample a wide range of values.
+At the end of the simulation, the biasing potential can be used to calculate the
+free energy of the system as a function of the collective variables.
+
+Accelerated Molecular Dynamics (aMD)
+------------------------------------
+
+aMD\ :cite:`Hamelberg2007` is another method that can be used when you do not know in
+advance what motions you want to accelerate.  It alters the potential energy surface
+by adding a "boost" potential whenever the potential energy is below a threshold.
+This makes local minima shallower and allows more frequent transitions between them.
+The boost can be applied to the total potential energy, to just a subset of interactions
+(typically the dihedral torsions), or both.  There are separate integrator classes
+for each of these options: :class:`AMDIntegrator`, :class:`AMDForceGroupIntegrator`,
+and :class:`DualAMDIntegrator`.
+
+
 .. _model-building-and-editing:
 
 Model Building and Editing
@@ -1666,7 +1715,7 @@ executing 1000 time steps at each temperature:
         :autonumber:`Example,simulated annealing`
 
 This code needs very little explanation.  The loop is executed 100 times.  Each
-time through, it adjusts the temperature of the :class:`LangevinIntegrator` and then
+time through, it adjusts the temperature of the :class:`BAOABLangevinIntegrator` and then
 calls :code:`step(1000)` to take 1000 time steps.
 
 Applying an External Force to Particles: a Spherical Container
@@ -1698,7 +1747,7 @@ coordinates.  Here is the code to do it:
         system.addForce(force)
         for i in range(system.getNumParticles()):
             force.addParticle(i, [])
-        integrator = LangevinIntegrator(300*kelvin, 91/picosecond, 0.002*picoseconds)
+        integrator = BAOABLangevinIntegrator(300*kelvin, 91/picosecond, 0.002*picoseconds)
         ...
 
     .. caption::

docs-source/usersguide/library.rst

@@ -243,14 +243,14 @@ simulation might look like:
         angles->addAngle(angle[i].particle1, angle[i].particle2,
             angle[i].particle3, angle[i].angle, angle[i].k);
     // ...create and initialize other force field terms in the same way
-    LangevinIntegrator integrator(temperature, friction, stepSize);
+    BAOABLangevinIntegrator integrator(temperature, friction, stepSize);
     Context context(system, integrator);
     context.setPositions(initialPositions);
     context.setVelocities(initialVelocities);
     integrator.step(10000);
 
 We create a System, add various Forces to it, and set parameters on both the
-System and the Forces.  We then create a LangevinIntegrator, initialize a
+System and the Forces.  We then create a BAOABLangevinIntegrator, initialize a
 Context in which to run a simulation, and instruct the Integrator to advance the
 simulation for 10,000 time steps.
 

docs-source/usersguide/references.bib

@@ -29,6 +29,18 @@
    type = {Journal Article}
 }
 
+@article{Barducci2008,
+  title = {Well-Tempered Metadynamics: A Smoothly Converging and Tunable Free-Energy Method},
+  author = {Barducci, Alessandro and Bussi, Giovanni and Parrinello, Michele},
+  journal = {Physical Review Letters},
+  volume = {100},
+  issue = {2},
+  pages = {020603},
+  year = {2008},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevLett.100.020603},
+}
+
 @article{Berendsen1987
    author = {Berendsen, H. J. C. and Grigera, J. R. and Straatsma, T. P.},
    title = {The missing term in effective pair potentials},
@@ -228,6 +240,19 @@
    type = {Journal Article}
 }
 
+@article{Leimkuhler2013,
+    author = {Leimkuhler, Benedict and Matthews, Charles},
+    title = {Rational Construction of Stochastic Numerical Methods for Molecular Sampling},
+    journal = {Applied Mathematics Research eXpress},
+    volume = {2013},
+    number = {1},
+    pages = {34-56},
+    year = {2012},
+    month = {06},
+    doi = {10.1093/amrx/abs010},
+    type = {Journal Article}
+}
+
 @article{Li2010
    author = {Li, D.W. and Br{\"u}schweiler, R.},
    title = {{NMR}-based protein potentials},
@@ -290,6 +315,18 @@
    type = {Journal Article}
 }
 
+@article{Marinari1992,
+    doi = {10.1209/0295-5075/19/6/002},
+    year = 1992,
+    publisher = {{IOP} Publishing},
+    volume = {19},
+    number = {6},
+    pages = {451--458},
+    author = {E Marinari and G Parisi},
+    title = {Simulated Tempering: A New Monte Carlo Scheme},
+    journal = {Europhysics Letters ({EPL})},
+}
+
 @article{Markland2008
    author = {Markland, Thomas E. and Manolopoulos, David E.},
    title = {An efficient ring polymer contraction scheme for imaginary time path integral simulations},

docs-source/usersguide/theory.rst

@@ -1338,6 +1338,21 @@ The integration is done using a leap-frog method similar to VerletIntegrator.
 :cite:`Izaguirre2010` The same comments about the offset between positions and
 velocities apply to this integrator as to that one.
 
+BAOABLangevinIntegrator
+***********************
+
+This integrator is similar to LangevinIntegerator, but it instead uses the BAOAB
+discretization. :cite:`Leimkuhler2013` This tends to produce more accurate
+sampling of configurational properties (such as free energies), but less
+accurate sampling of kinetic properties (such as mean kinetic energy).  Because
+configurational properties are much more important than kinetic ones in most
+simulations, this integrator is generally preferred over LangevinIntegrator.  It
+often allows one to use a larger time step while still maintaining similar or
+better accuracy.
+
+Unlike LangevinIntegrator, this does not use a leap-frog algorithm.  The
+positions and velocities all correspond to the same point in time.
+
 BrownianIntegrator
 ******************