Updated documentation on LangevinMiddleIntegrator

docs-source/usersguide/application.rst

@@ -217,7 +217,10 @@ It specifies a :class:`LangevinMiddleIntegrator`, which performs Langevin dynami
 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
-the step size (0.004 ps).
+the step size (0.004 ps).  Lots of other integration methods are also available.
+For example, if you wanted to simulate the system at constant energy rather than
+constant temperature you would use a :code:`VerletIntegrator`\ .  The available
+integration methods are listed in Section :ref:`integrators`.
 ::
 
     simulation = Simulation(pdb.topology, system, integrator)
@@ -1024,9 +1027,12 @@ 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.
+Detailed descriptions of all these integrators can be found in Section
+:ref:`integrators-theory`.  In addition to these built in integrators, lots of
+others are available as part of the `OpenMMTools <https://openmmtools.readthedocs.io>`_ package.
 
-BAOAB Langevin Integrator
--------------------------
+Langevin Middle Integrator
+--------------------------
 
 In the examples of the previous sections, we used Langevin integration:
 ::
@@ -1038,7 +1044,8 @@ the friction coefficient (1 ps\ :sup:`-1`\ ), and the step size (0.004 ps).  You
 are free to change these to whatever values you want.  Be sure to specify units
 on all values.  For example, the step size could be written either as
 :code:`0.004*picoseconds` or :code:`4*femtoseconds`\ .  They are exactly
-equivalent.
+equivalent.  Note that :code:`LangevinMiddleIntegrator` is a leapfrog
+integrator, so the velocities are offset by half a time step from the positions.
 
 Langevin Integrator
 -------------------
@@ -1047,7 +1054,7 @@ Langevin Integrator
 but it uses a different discretization of the Langevin equation.
 :code:`LangevinMiddleIntegrator` tends to produce more accurate configurational
 sampling, and therefore is preferred for most applications.  Also note that
-:code:`LangevinIntegrator` (unlike :code:`LangevinMiddleIntegrator`) is a leapfrog
+:code:`LangevinIntegrator`\ , like :code:`LangevinMiddleIntegrator`\ , is a leapfrog
 integrator, so the velocities are offset by half a time step from the positions.
 
 Leapfrog Verlet Integrator

docs-source/usersguide/references.bib

@@ -240,19 +240,6 @@
    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},
@@ -629,3 +616,15 @@
    year = {2015},
    type = {Journal Article}
 }
+
+@article{Zhang2019,
+    author = {Zhang, Zhijun and Liu, Xinzijian and Yan, Kangyu and Tuckerman, Mark E. and Liu, Jian},
+    title = {Unified Efficient Thermostat Scheme for the Canonical Ensemble with Holonomic or Isokinetic Constraints via Molecular Dynamics},
+    journal = {The Journal of Physical Chemistry A},
+    volume = {123},
+    number = {28},
+    pages = {6056-6079},
+    year = {2019},
+    doi = {10.1021/acs.jpca.9b02771},
+    type = {Journal Article}
+}

docs-source/usersguide/theory.rst

@@ -1278,6 +1278,8 @@ algorithm.  This can be used to implement algorithms such as lambda-dynamics,
 where a global parameter is integrated as a dynamic variable.
 
 
+.. _integrators-theory:
+
 Integrators
 ###########
 
@@ -1356,13 +1358,13 @@ this integrator as to VerletIntegrator.
 LangevinMiddleIntegrator
 ************************
 
-This integrator is similar to LangevinIntegerator, but it instead uses the BAOAB
-discretization. :cite:`Leimkuhler2013` In each step, the positions and velocities
+This integrator is similar to LangevinIntegerator, but it instead uses the LFMiddle
+discretization. :cite:`Zhang2019` In each step, the positions and velocities
 are updated as follows:
 
 
 .. math::
-   \mathbf{v}_{i}(t+\Delta t/2) = \mathbf{v}_{i}(t) + \mathbf{f}_{i}(t)\Delta t/2{m}_{i}
+   \mathbf{v}_{i}(t+\Delta t/2) = \mathbf{v}_{i}(t-\Delta t/2) + \mathbf{f}_{i}(t)\Delta t/{m}_{i}
 
 
 .. math::
@@ -1377,10 +1379,6 @@ are updated as follows:
    \mathbf{r}_{i}(t+\Delta t) = \mathbf{r}_{i}(t+\Delta t/2) + \mathbf{v'}_{i}(t+\Delta t/2)\Delta t/2
 
 
-.. math::
-   \mathbf{v}_{i}(t+\Delta t) = \mathbf{v'}_{i}(t+\Delta t/2) + \mathbf{f}_{i}(t+\Delta t)\Delta t/2{m}_{i}
-
-
 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
@@ -1390,13 +1388,10 @@ often allows one to use a larger time step while still maintaining similar or
 better accuracy.
 
 One disadvantage of this integrator is that it requires applying constraints
-three times per time step, compared to only once for LangevinIntegrator.  This
+twice per time step, compared to only once for LangevinIntegrator.  This
 can make it slightly slower for systems that involve constraints.  However, this
 usually is more than compensated by allowing you to use a larger time step.
 
-Unlike LangevinIntegrator, this does not use a leap-frog algorithm.  The
-positions and velocities all correspond to the same point in time.
-
 BrownianIntegrator
 ******************
 

openmmapi/include/openmm/CustomIntegrator.h

@@ -9,7 +9,7 @@
  * Biological Structures at Stanford, funded under the NIH Roadmap for        *
  * Medical Research, grant U54 GM072970. See https://simtk.org.               *
  *                                                                            *
- * Portions copyright (c) 2011-2019 Stanford University and the Authors.      *
+ * Portions copyright (c) 2011-2020 Stanford University and the Authors.      *
  * Authors: Peter Eastman                                                     *
  * Contributors:                                                              *
  *                                                                            *
@@ -245,18 +245,14 @@ namespace OpenMM {
  * integrator.addGlobalVariable("kT", kB*temperature);
  * integrator.addPerDofVariable("x1", 0);
  * integrator.addUpdateContextState();
- * integrator.addComputePerDof("v", "v + 0.5*dt*f/m");
+ * integrator.addComputePerDof("v", "v + dt*f/m");
+ * integrator.addConstrainVelocities();
  * integrator.addComputePerDof("x", "x + 0.5*dt*v");
- * integrator.addComputePerDof("x1", "x");
- * integrator.addConstrainPositions();
- * integrator.addComputePerDof("v", "v + 2*(x-x1)/dt");
  * integrator.addComputePerDof("v", "a*v + b*sqrt(kT/m)*gaussian");
  * integrator.addComputePerDof("x", "x + 0.5*dt*v");
  * integrator.addComputePerDof("x1", "x");
  * integrator.addConstrainPositions();
- * integrator.addComputePerDof("v", "v + 2*(x-x1)/dt");
- * integrator.addComputePerDof("v", "v + 0.5*dt*f/m");
- * integrator.addConstrainVelocities();
+ * integrator.addComputePerDof("v", "v + (x-x1)/dt");
  * </pre></tt>
  * 
  * Another feature of CustomIntegrator is that it can use derivatives of the

openmmapi/include/openmm/LangevinMiddleIntegrator.h

@@ -40,7 +40,7 @@ namespace OpenMM {
 
 /**
  * This is an Integrator which simulates a System using Langevin dynamics, with
- * the BAOAB discretization of Leimkuhler and Matthews (http://dx.doi.org/10.1093/amrx/abs010).
+ * the LFMiddle discretization (http://dx.doi.org/10.1021/acs.jpca.9b02771).
  * This method tend to produce more accurate configurational sampling than other
  * discretizations, such as the one used in LangevinIntegrator.
  */