Updates to documentation

docs-source/api-c++/Doxyfile.in

@@ -588,7 +588,7 @@ INPUT_ENCODING         = UTF-8
 # *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx
 # *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90
 
-FILE_PATTERNS          =
+FILE_PATTERNS          = *.h
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories
 # should be searched for input files as well. Possible values are YES and NO.

docs-source/developerguide/developer.rst

@@ -32,6 +32,8 @@ It is organized as follows:
   information relevant to writing OpenCL implementations of new features.
 * Chapter :ref:`the-cuda-platform` discusses the architecture of the CUDA Platform, providing
   information relevant to writing CUDA implementations of new features.
+* Chapter :ref:`common-compute` describes the Common Compute framework, which lets you
+  write a single implementation of a feature that can be used for both OpenCL and CUDA.
 
 
 This guide assumes you are already familiar with the public API and how to use
@@ -214,9 +216,9 @@ plugins happen to be loaded in.
 Creating New Platforms
 **********************
 
-One common type of plugin defines a new Platform.  There are three such plugins
-that come with OpenMM: one for the CPU Platform, one for the CUDA Platform, and
-one for the OpenCL Platform.
+One common type of plugin defines a new Platform.  There are four such plugins
+that come with OpenMM: one for the Reference platform, one for the CPU Platform,
+one for the CUDA Platform, and one for the OpenCL Platform.
 
 To define a new Platform, you must create subclasses of the various abstract
 classes in the OpenMM Low Level API: a subclass of Platform, one or more
@@ -974,5 +976,5 @@ value for a kernel argument or to access the elements of an array.  OpenCL and
 CUDA both define types for them, but they have different names, and in any case
 you want to avoid using OpenCL-specific or CUDA-specific types in common code.
 OpenMM therefore defines types for vectors in host code.  They have the same
-names as the correspond types in device code, only with the prefix :code:`mm_`\ ,
+names as the corresponding types in device code, only with the prefix :code:`mm_`\ ,
 for example :code:`mm_int2` and :code:`mm_float3`\ .
\ No newline at end of file

docs-source/developerguide/license.rst

-Portions copyright (c) 2011-2017 Stanford University and the Authors
+Portions copyright (c) 2011-2020 Stanford University and the Authors
 
 Contributors: Peter Eastman
 

docs-source/usersguide/theory.rst

@@ -1334,15 +1334,54 @@ components are chosen from a normal distribution with mean zero and variance
 :math:`2m_i \gamma k_B T`\ , where *T* is the temperature of
 the heat bath.
 
-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.
+The integration is done using the Langevin leap-frog method. :cite:`Izaguirre2010`
+In each step, the positions and velocities are updated as follows:
+
+
+.. math::
+   \mathbf{v}_{i}(t+\Delta t/2)=\mathbf{v}_{i}(t-\Delta t/2)\alpha+\mathbf{f}_{i}(t)(1-\alpha)/\gamma{m}_{i} + \sqrt{kT(1-\alpha^2)/m}R
+
+
+.. math::
+   \mathbf{r}_{i}(t+\Delta t)=\mathbf{r}_{i}(t)+\mathbf{v}_{i}(t+\Delta t/2)\Delta t
+
+
+where :math:`k` is Boltzmann's constant, :math:`T` is the temperature,
+:math:`\gamma` is the friction coefficient, :math:`R` is a normally distributed
+random number, and :math:`\alpha=\exp(-\gamma\Delta t)`.
+
+The same comments about the offset between positions and velocities apply to
+this integrator as to VerletIntegrator.
 
 BAOABLangevinIntegrator
 ***********************
 
 This integrator is similar to LangevinIntegerator, but it instead uses the BAOAB
-discretization. :cite:`Leimkuhler2013` This tends to produce more accurate
+discretization. :cite:`Leimkuhler2013` 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}
+
+
+.. math::
+   \mathbf{r}_{i}(t+\Delta t/2) = \mathbf{r}_{i}(t) + \mathbf{v}_{i}(t+\Delta t/2)\Delta t/2
+
+
+.. math::
+   \mathbf{v'}_{i}(t+\Delta t/2) = \mathbf{v}_{i}(t+\Delta t/2)\alpha + \sqrt{kT(1-\alpha^2)/m}R
+
+
+.. math::
+   \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
 configurational properties are much more important than kinetic ones in most
@@ -1350,6 +1389,11 @@ 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.
 
+One disadvantage of this integrator is that it requires applying constraints
+three times 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.
 

openmmapi/include/openmm/CustomIntegrator.h

@@ -50,8 +50,8 @@ namespace OpenMM {
  * with the particle positions and momenta.
  *
  * To create an integration algorithm, you first define a set of variables the
- * integrator will compute.  Variables come in two types: <i>global</i> variables
- * have a single value, while <i>per-DOF</i> variables have a value for every
+ * integrator will compute.  Variables come in two types: global variables
+ * have a single value, while per-DOF variables have a value for every
  * degree of freedom (x, y, or z coordinate of a particle).  You can define as
  * many variables as you want of each type.  The value of any variable can be
  * computed by the integration algorithm, or set directly by calling a method on
@@ -112,14 +112,14 @@ namespace OpenMM {
  * evaluated, a different value will be used.  When used in a per-DOF
  * expression, a different value will be used for every degree of freedom.
  * Note, however, that if this variable appears multiple times in a single
- * expression, the <i>same</i> value is used everywhere it appears in that
+ * expression, the same value is used everywhere it appears in that
  * expression.</li>
  * <li>gaussian: (either global or per-DOF, read-only) This is a Gaussian
  * distributed random number with mean 0 and variance 1.  Every time an expression
  * is evaluated, a different value will be used.  When used in a per-DOF
  * expression, a different value will be used for every degree of freedom.
  * Note, however, that if this variable appears multiple times in a single
- * expression, the <i>same</i> value is used everywhere it appears in that
+ * expression, the same value is used everywhere it appears in that
  * expression.</li>
  * <li>A global variable is created for every adjustable parameter defined
  * in the integrator's Context.</li>
@@ -218,6 +218,47 @@ namespace OpenMM {
  * integrator.addComputePerDof("angularMomentum", "m*cross(x, v)");
  * </pre></tt>
  * 
+ * Here are two more examples that may be useful as starting points for writing
+ * your own integrators.  The first one implements the algorithm used by the
+ * standard VerletIntegrator class.  This is a leapfrog algorithm, in contrast
+ * to the velocity Verlet algorithm shown above, so it only requires applying
+ * constraints once in each time step.
+ * 
+ * <tt><pre>
+ * CustomIntegrator integrator(dt);
+ * integrator.addPerDofVariable("x0", 0);
+ * integrator.addUpdateContextState();
+ * integrator.addComputePerDof("x0", "x");
+ * integrator.addComputePerDof("v", "v+dt*f/m");
+ * integrator.addComputePerDof("x", "x+dt*v");
+ * integrator.addConstrainPositions();
+ * integrator.addComputePerDof("v", "(x-x0)/dt");
+ * </pre></tt>
+ * 
+ * The second one implements the algorithm used by the standard
+ * BAOABLangevinIntegrator class.  kB is Boltzmann's constant.
+ * 
+ * <tt><pre>
+ * CustomIntegrator integrator(dt);
+ * integrator.addGlobalVariable("a", exp(-friction*dt));
+ * integrator.addGlobalVariable("b", sqrt(1-exp(-2*friction*dt)));
+ * integrator.addGlobalVariable("kT", kB*temperature);
+ * integrator.addPerDofVariable("x1", 0);
+ * integrator.addUpdateContextState();
+ * integrator.addComputePerDof("v", "v + 0.5*dt*f/m");
+ * 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();
+ * </pre></tt>
+ * 
  * Another feature of CustomIntegrator is that it can use derivatives of the
  * potential energy with respect to context parameters.  These derivatives are
  * typically computed by custom forces, and are only computed if a Force object
@@ -230,7 +271,7 @@ namespace OpenMM {
  *
  * An Integrator has one other job in addition to evolving the equations of motion:
  * it defines how to compute the kinetic energy of the system.  Depending on the
- * integration method used, simply summing mv<sup>2</sup>/2 over all degrees of
+ * integration method used, simply summing (mv^2)/2 over all degrees of
  * freedom may not give the correct answer.  For example, in a leapfrog integrator
  * the velocities are "delayed" by half a time step, so the above formula would
  * give the kinetic energy half a time step ago, not at the current time.
@@ -250,7 +291,7 @@ namespace OpenMM {
  * The kinetic energy expression may depend on the following pre-defined variables:
  * x, v, f, m, dt.  It also may depend on user-defined global and per-DOF variables,
  * and on the values of adjustable parameters defined  in the integrator's Context.
- * It may <i>not</i> depend on any other variable, such as the potential energy,
+ * It may not depend on any other variable, such as the potential energy,
  * the force from a single force group, or a random number.
  *
  * Expressions may involve the operators + (add), - (subtract), * (multiply), / (divide), and ^ (power), and the following