Add a section at the end of the manual about stochastic forces, integrators, and

random numbers. Add 2 citations about Langevin synchronization. Convert the references.bib file to UNIX line endings.

Add a section at the end of the manual about stochastic forces, integrators, and
random numbers. Add 2 citations about Langevin synchronization. Convert the references.bib file to UNIX line endings.
c2191b61 · Jason Swails · be8bd376 · c2191b61 · c2191b61
Commit c2191b61 authored Jan 15, 2015 by Jason Swails
Hide whitespace changes
Inline Side-by-side

Showing with 537 additions and 447 deletions

docs-source/usersguide/references.bib docs-source/usersguide/references.bib +475 -447

docs-source/usersguide/theory.rst docs-source/usersguide/theory.rst +62 -0

No files found.
--- a/docs-source/usersguide/references.bib
+++ b/docs-source/usersguide/references.bib
 @article{Andersen1980
   author = {Andersen, Hans C.},
   title = {Molecular dynamics simulations at constant pressure and/or temperature},
   journal = {Journal of Chemical Physics},
   volume = {72},
   number = {4},
   pages = {2384-2393},
   year = {1980},
   type = {Journal Article}
 }
 @article{Aqvist2004
   author = {Åqvist, Johan and Wennerström, Petra and Nervall, Martin and Bjelic, Sinisa and Brandsdal, Bjørn O.},
   title = {Molecular dynamics simulations of water and biomolecules with a {Monte Carlo} constant pressure algorithm},
   journal = {Chemical Physics Letters},
   volume = {384},
   pages = {288-294},
   year = {2004},
   type = {Journal Article}
 }
 @article{Berendsen1987
   author = {Berendsen, H. J. C. and Grigera, J. R. and Straatsma, T. P.},
   title = {The missing term in effective pair potentials},
   journal = {Journal of Physical Chemistry},
   volume = {91},
   pages = {6269-6271},
   year = {1987},
   type = {Journal Article}
 }
 @article{Ceriotti2010
   author = {Ceriotti, M. and Parrinello, M. and Markland, Thomas E. and Manolopoulos, David E.},
   title = {Efficient stochastic thermostatting of path integral molecular dynamics},
   journal = {Journal of Chemical Physics},
   volume = {133},
   number = {12},
   year = {2010},
   type = {Journal Article}
 }
 @article{Chow1995
   author = {Chow, Kim-Hung and Ferguson, David M.},
   title = {Isothermal-isobaric molecular dynamics simulations with {Monte Carlo} volume sampling},
   journal = {Computer Physics Communications},
   volume = {91},
   pages = {283-289},
   year = {1995},
   type = {Journal Article}
 }
 @article{Craig2004
   author = {Craig, I. R. and Manolopoulos, David E.},
   title = {Quantum statistics and classical mechanics: Real time correlation functions from ring polymer molecular dynamics},
   journal = {Journal of Chemical Physics},
   volume = {121},
   pages = {3368-3373},
   year = {2004},
   type = {Journal Article}
 }
 @article{Duan2003
   author = {Duan, Y.; Wu, C. and Chowdhury, S. and Lee, M.C. and Xiong, G. and Zhang, W. and Yang, R. and Cieplak, P. and Luo, R. and Lee, T.},
   title = {A point-charge force field for molecular mechanics simulations of proteins based on condensed-phase quantum mechanical calculations},
   journal = {Journal of Computational Chemistry},
   volume = {24},
   pages = {1999-2012},
   year = {2003},
   type = {Journal Article}
 }
 @article{Essmann1995
   author = {Essmann, Ulrich and Perera, Lalith and Berkowitz, Max L. and Darden, Tom and Lee, Hsing and Pedersen, Lee G.},
   title = {A smooth particle mesh {Ewald} method},
   journal = {Journal of Chemical Physics},
   volume = {103},
   number = {19},
   pages = {8577-8593},
   year = {1995},
   type = {Journal Article}
 }
 @article{Hall1984
   author = {Hall, Randall W. and Berne, B. J.},
   title = {Nonergodicity in path integral molecular dynamics},
   journal = {Journal of Chemical Physics},
   volume = {81},
   number = {8},
   year = {1984},
   type = {Journal Article}
 }
 @article{Hawkins1995
   author = {Hawkins, Gregory D. and Cramer, Christopher J. and Truhlar, Donald G.},
   title = {Pairwise solute descreening of solute charges from a dielectric medium},
   journal = {Chemical Physics Letters},
   volume = {246},
   number = {1-2},
   pages = {122-129},
   year = {1995},
   type = {Journal Article}
 }
 @article{Horn2004
   author = {Horn, Hans W. and Swope, William C. and Pitera, Jed W. and Madura, Jeffry D. and Dick, Thomas J. and Hura, Greg L. and Head-Gordon, Teresa},
   title = {Development of an improved four-site water model for biomolecular simulations: {TIP4P-Ew}},
   journal = {Journal of Chemical Physics},
   volume = {120},
   pages = {9665-9678},
   year = {2004},
   type = {Journal Article}
 }
 @article{Hornak2006
   author = {Hornak, V. and Abel, R. and Okur, A. and Strockbine, B. and Roitberg, A. and Simmerling, C.},
   title = {Comparison of multiple {Amber} force fields and development of improved protein backbone parameters},
   journal = {Proteins},
   volume = {65},
   pages = {712-725},
   year = {2006},
   type = {Journal Article}
 }
 @article{Izaguirre2010
   author = {Izaguirre, Jesús A. and Sweet, Chris R. and Pande, Vijay S.},
   title = {Multiscale dynamics of macromolecules using {Normal Mode Langevin}},
   journal = {Pacific Symposium on Biocomputing},
   volume = {15},
   pages = {240-251},
   year = {2010},
   type = {Journal Article}
 }
 @article{Jorgensen1983
   author = {Jorgensen, William L. and Chandrasekhar, Jayaraman and Madura, Jeffry D. and Impey, Roger W. and Klein, Michael L.},
   title = {Comparison of simple potential functions for simulating liquid water},
   journal = {Journal of Chemical Physics},
   volume = {79},
   pages = {926-935},
   year = {1983},
   type = {Journal Article}
 }
 @inbook{Kollman1997
   author = {Kollman, P.A. and Dixon, R. and Cornell, W. and Fox, T. and Chipot, C. and Pohorille, A.},
   title = {Computer Simulation of Biomolecular Systems},
   editor = {Wilkinson, A. and Weiner, P. and van Gunsteren, Wilfred F.},
   publisher = {Elsevier},
   volume = {3},
   pages = {83-96},
   year = {1997},
   type = {Book Section}
 }
 @article{Labute2008
   author = {Labute, Paul},
   title = {The generalized {Born}/volume integral implicit solvent model: Estimation of the free energy of hydration using {London} dispersion instead of atomic surface area},
   journal = {Journal of Computational Chemistry},
   volume = {29},
   number = {10},
   pages = {1693-1698},
   year = {2008},
   type = {Journal Article}
 }
 @article{Lamoureux2006
   author = {Lamoureux, Guillaume and Harder, Edward and Vorobyov, Igor V. and Roux, Benoit and MacKerell Jr., Alexander D.},
   title = {A polarizable model of water for molecular dynamics simulations of biomolecules},
   journal = {Chemical Physics Letters},
   volume = {418},
   number = {1-3},
   pages = {245-249},
   year = {2006},
   type = {Journal Article}
 }
 @article{Lamoureux2003
   author = {Lamoureux, Guillaume and Roux, Benoit},
   title = {Modeling induced polarization with classical {Drude} oscillators: Theory and molecular dynamics simulation algorithm},
   journal = {Journal of Chemical Physics},
   volume = {119},
   number = {6},
   pages = {3025-3039},
   year = {2003},
   type = {Journal Article}
 }
 @article{Li2010
   author = {Li, D.W. and Br{\"u}schweiler, R.},
   title = {{NMR}-based protein potentials},
   journal = {Angewandte Chemie International Edition},
   volume = {49},
   pages = {6778-6780},
   year = {2010},
   type = {Journal Article}
 }
 @article{Lindorff-Larsen2010
   author = {Lindorff-Larsen, K. and Piana, S. and Palmo, K. and Maragakis, P. and Klepeis, J. and Dror, R.O. and Shaw, D.E.},
   title = {Improved side-chain torsion potentials for the {Amber ff99SB} protein force field},
   journal = {Proteins},
   volume = {78},
   pages = {1950-1958},
   year = {2010},
   type = {Journal Article}
 }
 @article{Liu1989
   author = {Liu, Dong C. and Nocedal, Jorge},
   title = {On the Limited Memory {BFGS} Method For Large Scale Optimization},
   journal = {Mathematical Programming},
   volume = {45},
   pages = {503-528},
   year = {1989},
   type = {Journal Article}
 }
 @article{Lopes2013,
    author = {Lopes, Pedro E. M. and Huang, Jing and Shim, Jihyun and Luo, Yun and Li, Hui and Roux, Benoît and MacKerell, Alexander D.},
    title = {Polarizable Force Field for Peptides and Proteins Based on the Classical {Drude} Oscillator},
    journal = {Journal of Chemical Theory and Computation},
    volume = {9},
    number = {12},
    pages = {5430-5449},
    year = {2013},
    type = {Journal Article}
 }
 @article{Mahoney2000
   author = {Mahoney, Michael W. and Jorgensen, William L.},
   title = {A five-site model for liquid water and the reproduction of the density anomaly by rigid, nonpolarizable potential functions},
   journal = {Journal of Chemical Physics},
   volume = {112},
   pages = {8910-8922},
   year = {2000},
   type = {Journal Article}
 }
 @article{Markland2008
   author = {Markland, Thomas E. and Manolopoulos, David E.},
   title = {An efficient ring polymer contraction scheme for imaginary time path integral simulations},
   journal = {Journal of Chemical Physics},
   volume = {129},
   number = {2},
   year = {2008},
   type = {Journal Article}
 }
 @article{Mongan2007
   author = {Mongan, John and Simmerling, Carlos and McCammon, J. Andrew and Case, David A. and Onufriev, Alexey},
   title = {Generalized {Born} model with a simple, robust molecular volume correction},
   journal = {Journal of Chemical Theory and Computation},
   volume = {3},
   number = {1},
   pages = {156-169},
   year = {2007},
   type = {Journal Article}
 }
 @article{Nguyen2013
   author = {Nguyen, Hai and Roe, Daniel R. and Simmerling, Carlos},
   title = {Improved Generalized {Born} Solvent Model Parameters for Protein Simulations},
   journal = {Journal of Chemical Theory and Computation},
   volume = {9},
   number = {4},
   pages = {2020-2034},
   year = {2013},
   type = {Journal Article}
 }
 @article{Onufriev2004
   author = {Onufriev, Alexey and Bashford, Donald and Case, David A.},
   title = {Exploring protein native states and large-scale conformational changes with a modified generalized {Born} model},
   journal = {Proteins},
   volume = {55},
   number = {22},
   pages = {383-394},
   year = {2004},
   type = {Journal Article}
 }
 @article{Parrinello1984
   author = {Parrinello, M. and Rahman, A.},
   title = {Study of an {F} center in molten {KCl}},
   journal = {Journal of Chemical Physics},
   volume = {80},
   number = {2},
   pages = {860-867},
   year = {1984},
   type = {Journal Article}
 }
 @misc{Ponder
   author = {Ponder, Jay W.},
   title = {Personal communication},
   type = {Personal Communication}
 }
 @article{Ren2002
   author = {Ren, P. and Ponder, Jay W.},
   title = {A Consistent Treatment of Inter- and Intramolecular Polarization in Molecular Mechanics Calculations},
   journal = {Journal of Computational Chemistry},
   volume = {23},
   pages = {1497-1506},
   year = {2002},
   type = {Journal Article}
 }
 @article{Ren2003
   author = {Ren, P. and Ponder, Jay W.},
   title = {Polarizable Atomic Multipole Water Model for Molecular Mechanics Simulation},
   journal = {Journal of Physical Chemistry B},
   volume = {107},
   pages = {5933-5947},
   year = {2003},
   type = {Journal Article}
 }
 @article{Schaefer1998
   author = {Schaefer, Michael and Bartels, Christian and Karplus, Martin},
   title = {Solution conformations and thermodynamics of structured peptides: molecular dynamics simulation with an implicit solvation model},
   journal = {Journal of Molecular Biology},
   volume = {284},
   number = {3},
   pages = {835-848},
   year = {1998},
   type = {Journal Article}
 }
 @article{Schnieders2007
   author = {Schnieders, Michael J. and Ponder, Jay W.},
   title = {Polarizable Atomic Multipole Solutes in a Generalized {Kirkwood} Continuum},
   journal = {Journal of Chemical Theory and Computation},
   volume = {3},
   pages = {2083-2097},
   year = {2007},
   type = {Journal Article}
 }
 @article{Shirts2008
   author = {Shirts, Michael R. and Chodera, John D.},
   title = {Statistically optimal analysis of samples from multiple equilibrium states},
   journal = {Journal of Chemical Physics},
   volume = {129},
   pages = {124105},
   year = {2008},
   type = {Journal Article}
 }
 @article{Shi2013
   author = {Shi, Yue and Xia, Zhen and Zhang, Jiajing and Best, Robert and Wu, Chuanjie and Ponder, Jay W. and Ren, Pengyu},
   title = {Polarizable Atomic Multipole-Based {AMOEBA} Force Field for Proteins},
   journal = {Journal of Chemical Theory and Computation},
   volume = {9},
   number = {9},
   pages = {4046-4063},
   year = {2013},
   type = {Journal Article}
 }
 @article{Shirts2007
   author = {Shirts, Michael R. and Mobley, David L. and Chodera, John D. and Pande, Vijay S.},
   title = {Accurate and Efficient Corrections for Missing Dispersion Interactions in Molecular Simulations},
   journal = {Journal of Physical Chemistry B},
   volume = {111},
   pages = {13052-13063},
   year = {2007},
   type = {Journal Article}
 }
 @article{Shirts2005
   author = {Shirts, Michael R. and Pande, Vijay S.},
   title = {Solvation free energies of amino acid side chain analogs for common molecular mechanics water models},
   journal = {Journal of Chemical Physics},
   volume = {132},
   pages = {134508},
   year = {2005},
   type = {Journal Article}
 }
-@article{Srinivasan1999
+@article{Sindhikara2009,
-   author = {Srinivasan, J and Trevathan, M. W. and Beroza, P. and Case, D. A.},
+  author =   {Sindhikara, Daniel J. and Kim, Seonah and Voter,
-   title = {Application of a pairwise generalized {Born} model to proteins and nucleic acids: inclusion of salt effects},
+                  Arthur F. and Roitberg, Adrian E.},
-   journal = {Theor. Chem. Acc.},
+  title =    {{Bad Seeds Sprout Perilous Dynamics: Stochastic
-   volume = {101},
+                  Thermostat Induced Trajectory Synchronization in
-   pages = {426-434},
+                  Biomolecules}},
-   year = {1999},
+  journal =  {Journal of Chemical Theory and Computation},
-   type = {Journal Article}
+  year =     2009,
-}
+  volume =   5,
+  number =   6,
-@article{Thole1981
+  pages =    {1624--1631},
-   author = {Thole, B. T.},
+  month =    {April},
-   title = {Molecular polarizabilities calculated with a modified dipole interaction},
+}
-   journal = {Chemical Physics},
-   volume = {59},
+@article{Srinivasan1999
-   number = {3},
+   author = {Srinivasan, J and Trevathan, M. W. and Beroza, P. and Case, D. A.},
-   pages = {341-350},
+   title = {Application of a pairwise generalized {Born} model to proteins and nucleic acids: inclusion of salt effects},
-   year = {1981},
+   journal = {Theor. Chem. Acc.},
-   type = {Journal Article}
+   volume = {101},
-}
+   pages = {426-434},
+   year = {1999},
-@misc{Tinker
+   type = {Journal Article}
-   author = {Ponder, Jay W.},
+}
-   title = {{TINKER - Software Tools for Molecular Design, 4.2}},
-   year = {2004}
+@article{Thole1981
-}
+   author = {Thole, B. T.},
+   title = {Molecular polarizabilities calculated with a modified dipole interaction},
-@article{Tironi1995
+   journal = {Chemical Physics},
-   author = {Tironi, Ilario G. and Sperb, René and Smith, Paul E. and van Gunsteren, Wilfred F.},
+   volume = {59},
-   title = {A generalized reaction field method for molecular dynamics simulations},
+   number = {3},
-   journal = {Journal of Chemical Physics},
+   pages = {341-350},
-   volume = {102},
+   year = {1981},
-   number = {13},
+   type = {Journal Article}
-   pages = {5451-5459},
+}
-   year = {1995},
-   type = {Journal Article}
+@misc{Tinker
-}
+   author = {Ponder, Jay W.},
+   title = {{TINKER - Software Tools for Molecular Design, 4.2}},
-@article{Toukmaji1996
+   year = {2004}
-   author = {Toukmaji, Abdulnour Y.  and Board Jr, John A.},
+}
-   title = {{Ewald} summation techniques in perspective: a survey},
-   journal = {Computer Physics Communications},
+@article{Tironi1995
-   volume = {95},
+   author = {Tironi, Ilario G. and Sperb, René and Smith, Paul E. and van Gunsteren, Wilfred F.},
-   pages = {73-92},
+   title = {A generalized reaction field method for molecular dynamics simulations},
-   year = {1996},
+   journal = {Journal of Chemical Physics},
-   type = {Journal Article}
+   volume = {102},
-}
+   number = {13},
+   pages = {5451-5459},
-@article{Wang2000
+   year = {1995},
-   author = {Wang, J. and Cieplak, P. and Kollman, P.A.},
+   type = {Journal Article}
-   title = {How well does a restrained electrostatic potential ({RESP}) model perform in calculating conformational energies of organic and biological molecules?},
+}
-   journal = {Journal of Computational Chemistry},
-   volume = {21},
+@article{Toukmaji1996
-   pages = {1049-1074},
+   author = {Toukmaji, Abdulnour Y.  and Board Jr, John A.},
-   year = {2000},
+   title = {{Ewald} summation techniques in perspective: a survey},
-   type = {Journal Article}
+   journal = {Computer Physics Communications},
-}
+   volume = {95},
+   pages = {73-92},
-@article{Wang2014
+   year = {1996},
-   author = {Wang, Lee-Ping and Martinez, Todd J. and Pande, Vijay S.},
+   type = {Journal Article}
-   title = {Building force fields: an automatic, systematic, and reproducible approach},
+}
-   journal = {Journal of Physical Chemistry Letters},
-   volume = {5},
+@article{Uberuaga2004,
-   pages = {1885-1891},
+  author =   {Blas P. Uberuaga and Marian Anghel and Arthur
-   year = {2014},
+                  F. Voter},
-   type = {Journal Article}
+  title =    {{Synchronization of trajectories in canonical
-}
+                  molecular-dynamics simulations: observation,
+                  explanation, and exploitation}},
+  journal =  {Journal of Chemical Physics},
+  year =     2004,
+  key =      {synchronization, parallelization},
+  volume =   120,
+  number =   14,
+  pages =    {6363--6374},
+}
+@article{Wang2000
+   author = {Wang, J. and Cieplak, P. and Kollman, P.A.},
+   title = {How well does a restrained electrostatic potential ({RESP}) model perform in calculating conformational energies of organic and biological molecules?},
+   journal = {Journal of Computational Chemistry},
+   volume = {21},
+   pages = {1049-1074},
+   year = {2000},
+   type = {Journal Article}
+}
+@article{Wang2014
+   author = {Wang, Lee-Ping and Martinez, Todd J. and Pande, Vijay S.},
+   title = {Building force fields: an automatic, systematic, and reproducible approach},
+   journal = {Journal of Physical Chemistry Letters},
+   volume = {5},
+   pages = {1885-1891},
+   year = {2014},
+   type = {Journal Article}
+}
--- a/docs-source/usersguide/theory.rst
+++ b/docs-source/usersguide/theory.rst
@@ -1379,3 +1379,65 @@ specific types of rules.  They are:
 .. math::
   \mathbf{r}=\mathbf{o}+p_1\mathbf{\hat{x}}+p_2\mathbf{\hat{y}}+p_3\mathbf{\hat{z}}
 ..
+Random Numbers with Stochastic Integrators and Forces
+*****************************************************
+OpenMM includes many stochastic integrators and forces that make extensive use
+of random numbers. It is impossible to generate truly random numbers on a
+computer like you would with a dice roll or coin flip in real life---instead
+programs rely on pseudo-random number generators (PRNGs) that take some sort of
+initial "seed" value and steps through a sequence of seemingly random numbers.
+The exact implementation of the PRNGs is not important (in fact, each platform
+may have its own PRNG whose performance is optimized for that hardware).  What
+*is* important, however, is that the PRNG must generate a uniform distribution
+of random numbers between 0 and 1. Random numbers drawn from this distribution
+can be manipulated to yield random integers in a desired range or even a random
+number from a different type of probability distribution function (e.g., a
+normal distribution).
+What this means is that the random numbers used by integrators and forces within
+OpenMM cannot have any discernible pattern to them.  Patterns can be induced in
+PRNGs in two principle ways:
+    1. The PRNG uses a bad algorithm with a short period.
+    2. Two PRNGs are started using the same seed
+All PRNG algorithms in common use are periodic---that is their sequence of
+random numbers repeats after a given *period*, defined by the number of "unique"
+random numbers in the repeating pattern.  As long as this period is longer than
+the total number of random numbers your application requires (preferably by
+orders of magnitude), the first problem described above is avoided. All PRNGs
+employed by OpenMM have periods far longer than any current simulation can cycle
+through.
+Point two is far more common in biomolecular simulation, and can result in very
+strange artifacts that may be difficult to detect. For example, with Langevin
+dynamics, two simulations that use the same sequence of random numbers appear to
+synchronize in their global movements.\ :cite:`Uberuaga2004`\
+:cite:`Sindhikara2009` It is therefore very important that the stochastic forces
+and integrators in OpenMM generate unique sequences of pseudo-random numbers not
+only within a single simulation, but between two different simulations of the
+same system as well (including any restarts of previous simulations).
+Every stochastic force and integrator that does (or could) make use of random
+numbers has two instance methods attached to it: ``getRandomNumberSeed()`` and
+``setRandomNumberSeed(int seed)``. If you set a unique random seed for two
+different simulations (or different forces/integrators if applicable), OpenMM
+guarantees that the generated sequences of random numbers will be different (by
+contrast, no guarantee is made that the same seed will result in identical
+random number sequences).
+Since breaking simulations up into pieces and/or running multiple replicates of
+a system to obtain more complete statistics is common practice, a new strategy
+has been employed for OpenMM versions 6.3 and later with the aim of trying to
+ensure that each simulation will be started with a unique random seed. A random
+seed value of 0 (the default) will cause a unique random seed to be generated
+when a new ``Context`` is instantiated.
+Prior to the introduction of this feature, deserializing a serialized
+``System`` XML file would result in each stochastic force or integrator being
+assigned the same random seed as the original instance that was serialized. If
+you use a ``System`` XML file generated by a version of OpenMM older than 6.3
+to start a new simulation, you should manually set the random number seed of
+each stochastic force or integrator to 0 (or another unique value).