Merge branch 'master' of https://github.com/peastman/openmm

docs/usersguide/header.rst

+.. role:: code
+.. raw:: html
+
+    <style> .code {font-family:monospace;} </style>
+    <style> .caption {text-align:center;} </style>

docs/usersguide/index.rst

+.. include:: header.rst
+
+####################################
+OpenMM Users Manual and Theory Guide
+####################################
+
+
+Portions copyright (c) 2008-2014 Stanford University and the Authors
+
+Contributors:  Kyle Beauchamp, Christopher Bruns, Peter Eastman, Mark
+Friedrichs, Joy P. Ku, Vijay Pande, Randy Radmer, Michael Sherman, Tom Markland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this document (the "Document"), to deal in the Document without restriction,
+including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Document, and to permit
+persons to whom the Document is furnished to do so, subject to the following
+conditions:
+
+This copyright and permission notice shall be included in all copies or
+substantial portions of the Document.
+
+THE DOCUMENT 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,
+CONTRIBUTORS 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 DOCUMENT OR THE USE OR OTHER DEALINGS IN THE
+DOCUMENT.
+
+
+.. toctree::
+   :numbered:
+   :maxdepth: 3
+
+   introduction   
+   application
+   library
+   theory
+   zbibliography
+

docs/usersguide/introduction.rst

+.. include:: header.rst
+
+Introduction
+############
+
+OpenMM consists of two parts:
+
+#. A set of libraries that lets programmers easily add molecular simulation
+   features to their programs
+#. An “application layer” that exposes those features to end users who just want
+   to run simulations
+
+
+This guide is devided into three sections:
+
+* Part I (Chapters :ref:`the-openmm-application-layer-introduction`\ -\ :ref:`creating-force-fields`\ )
+  describes the application layer.  It is relevant to all users, but especially relevant to people
+  who want to use OpenMM as a stand-alone application for running simulations.
+* Part II (Chapters :ref:`the-openmm-library-introduction`\ -\ :ref:`drude-plugin`\ )
+  describes how to use the OpenMM libraries within your own applications.  It is primarily
+  relevant to programmers who want to write simulation applications.
+* Part III (Chapters :ref:`the-theory-behind-openmm-introduction`\ -\ :ref:`other-features`\ )
+  describes the mathematical theory behind the features found in OpenMM.  It is relevant to all users.
+
+
+Online Resources
+****************
+
+You can find more documentation and other material at our website
+http://simtk.org/home/openmm.   Among other things there is a discussion forum,
+a wiki, and videos of lectures on using OpenMM.
+
+
+Referencing OpenMM
+******************
+
+Any work that uses OpenMM should cite the following publication:
+
+P. Eastman, M. S. Friedrichs, J. D. Chodera, R. J. Radmer, C. M. Bruns, J. P.
+Ku, K. A. Beauchamp, T. J. Lane, L.-P. Wang, D. Shukla, T. Tye, M. Houston, T.
+Stich, C. Klein, M. R. Shirts, and V. S. Pande. "OpenMM 4: A Reusable,
+Extensible, Hardware Independent Library for High Performance Molecular
+Simulation." J. Chem. Theor. Comput. 9(1): 461-469. (2013).
+
+We depend on academic research grants to fund the OpenMM development efforts;
+citations of our publication will help demonstrate the value of OpenMM.
+
+
+Acknowledgments
+***************
+
+OpenMM software and all related activities, such as this manual, are funded by
+the Simbios National Center for Biomedical Computing through the National
+Institutes of Health Roadmap for Medical Research, Grant U54 GM072970.
+Information on the National Centers can be found at
+http://nihroadmap.nih.gov/bioinformatics.
+

docs/usersguide/numsec.py

+"""
+Changes section references to be the section number
+instead of the title of the section.
+"""
+
+from docutils import nodes
+import sphinx.domains.std
+
+class CustomStandardDomain(sphinx.domains.std.StandardDomain):
+
+    def __init__(self, env):
+        env.settings['footnote_references'] = 'superscript'
+        sphinx.domains.std.StandardDomain.__init__(self, env)
+
+    def resolve_xref(self, env, fromdocname, builder,
+                     typ, target, node, contnode):
+        res = super(CustomStandardDomain, self).resolve_xref(env, fromdocname, builder,
+                                                            typ, target, node, contnode)
+        
+        if res is None:
+            return res
+        
+        if typ == 'ref' and not node['refexplicit']:
+            docname, labelid, sectname = self.data['labels'].get(target, ('','',''))
+            res['refdocname'] = docname
+        
+        return res
+
+def doctree_resolved(app, doctree, docname):
+    secnums = app.builder.env.toc_secnumbers
+    for node in doctree.traverse(nodes.reference):
+        if 'refdocname' in node:
+            refdocname = node['refdocname']
+            if refdocname in secnums:
+                secnum = secnums[refdocname]
+                emphnode = node.children[0]
+                textnode = emphnode.children[0]
+                
+                toclist = app.builder.env.tocs[refdocname]
+                anchorname = None
+                for refnode in toclist.traverse(nodes.reference):
+                    if refnode.astext() == textnode.astext():
+                        anchorname = refnode['anchorname']
+                if anchorname is None:
+                    continue
+                linktext = '.'.join(map(str, secnum[anchorname]))
+                node.replace(emphnode, nodes.Text(linktext))
+
+def setup(app):
+    app.override_domain(CustomStandardDomain)
+    app.connect('doctree-resolved', doctree_resolved)
+

docs/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{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{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{Thole1981
+   author = {Thole, B. T.},
+   title = {Molecular polarizabilities calculated with a modified dipole interaction},
+   journal = {Chemical Physics},
+   volume = {59},
+   number = {3},
+   pages = {341-350},
+   year = {1981},
+   type = {Journal Article}
+}
+
+@article{Tironi1995
+   author = {Tironi, Ilario G. and Sperb, René and Smith, Paul E. and van Gunsteren, Wilfred F.},
+   title = {A generalized reaction field method for molecular dynamics simulations},
+   journal = {Journal of Chemical Physics},
+   volume = {102},
+   number = {13},
+   pages = {5451-5459},
+   year = {1995},
+   type = {Journal Article}
+}
+
+@article{Toukmaji1996
+   author = {Toukmaji, Abdulnour Y.  and Board Jr, John A.},
+   title = {Ewald summation techniques in perspective: a survey},
+   journal = {Computer Physics Communications},
+   volume = {95},
+   pages = {73-92},
+   year = {1996},
+   type = {Journal Article}
+}
+
+@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}
+}
+

docs/usersguide/samepage.py

+from docutils.parsers.rst import Directive
+from docutils.nodes import compound, raw
+
+class SamepageDirective(Directive):
+    
+    has_content = True
+
+    def run(self):
+        prefix = raw('', '\\par\\begin{samepage}', format='latex')
+        suffix = raw('', '\\end{samepage}\\par', format='latex')
+        text = '\n'.join(self.content)
+        content_node = compound(rawsource=text)
+        self.state.nested_parse(self.content, self.content_offset, content_node)
+        return [prefix, content_node, suffix]
+
+def setup(app):
+    app.add_directive('samepage', SamepageDirective)

docs/usersguide/zbibliography.rst

+.. only:: html
+
+   Bibliography
+   ############
+
+.. bibliography:: references.bib
+   :style: unsrt