Merge pull request #580 from peastman/docs

Updates to documentation for 6.1

docs-source/developerguide/developer.rst

@@ -578,8 +578,8 @@ The following preprocessor macros will also have been defined:
 Finally, two output variables will have been defined:
 
 #. You should add the energy of the interaction to :code:`tempEnergy`\ .
-#. You should add the derivative of the energy with respect to the inter-
-   particle distance to :code:`dEdR`\ .
+#. You should add the derivative of the energy with respect to the inter-particle
+   distance to :code:`dEdR`\ .
 
 
 You can also define arbitrary per-particle parameters by calling 

docs-source/usersguide/application.rst

 .. include:: header.rst
 
+.. default-domain:: py
+
 .. _the-openmm-application-layer-introduction:
 
 The OpenMM Application Layer: Introduction
@@ -16,7 +18,7 @@ Nearly all molecular simulation applications ask you to write some sort of
 script happens to be written in Python.  But it is no harder to write than those
 for most other applications, and this guide will teach you everything you need
 to know.  There is even a graphical interface that can write the script for you
-based on a simple set of options (see section :ref:`the-script-builder-application`),
+based on a simple set of options (see Section :ref:`the-script-builder-application`),
 so you never need to type a single line of code!
 
 On the other hand, if you don’t mind doing a little programming, this approach
@@ -36,17 +38,20 @@ Follow these instructions to install OpenMM.  There also is an online
 troubleshooting guide that describes common problems and how to fix them
 (http://wiki.simtk.org/openmm/FAQApp).
 
+.. _installing-on-mac-os-x:
+
 Installing on Mac OS X
 **********************
 
 OpenMM works on Mac OS X 10.7 or later.  GPU acceleration is currently only
 supported on Nvidia GPUs, not on AMD or Intel GPUs.
 
-\ **Important:** A serious bug was introduced in Mac OS X 10.7.5 that prevents
-OpenMM’s OpenCL platform from working correctly.  At the time of this writing,
-the bug is present in all versions from 10.7.5 onward.  The CUDA platform (see
-below) is not affected by the bug, so if you have an affected version of OS X,
-you should use it instead of the OpenCL platform.
+.. warning::
+   A serious bug was introduced in Mac OS X 10.7.5 that prevents
+   OpenMM’s OpenCL platform from working correctly.  At the time of this writing,
+   the bug is present in all versions from 10.7.5 onward.  The CUDA platform (see
+   below) is not affected by the bug, so if you have an affected version of OS X,
+   you should use it instead of the OpenCL platform.
 
 1. Download the pre-compiled binary of OpenMM for Mac OS X, then double click
 the .zip file to expand it.
@@ -71,7 +76,7 @@ but the performance of particle mesh Ewald (PME) will be much worse.
 ::
 
     cd <openmm_directory>
-    
+
 where :code:`<openmm_directory>` is the path to the OpenMM folder.  Then run
 the install script by typing
 ::
@@ -94,16 +99,16 @@ want to run OpenMM in another Terminal window, you must type the above command
 in the new window.
 
 If you plan to use the CUDA platform, OpenMM also needs to locate the CUDA
-kernel compiler (nvcc).  By default it looks for it in the location
+kernel compiler (:program:`nvcc`).  By default it looks for it in the location
 :file:`/usr/local/cuda/bin/nvcc`.  If you have installed the CUDA toolkit in a different
-location, you can set OPENMM_CUDA_COMPILER to tell OpenMM where to find it.  For
+location, you can set :envvar:`OPENMM_CUDA_COMPILER` to tell OpenMM where to find it.  For
 example,
 ::
 
     export OPENMM_CUDA_COMPILER=/opt/CUDA/cuda-6.0/bin/nvcc
 
-7. Verify your installation by running the “testInstallation.py” script found in
-the “examples” folder of your OpenMM installation.  To run it, cd to the
+7. Verify your installation by running the :file:`testInstallation.py` script found in
+the :file:`examples` folder of your OpenMM installation.  To run it, cd to the
 examples folder and type
 ::
 
@@ -119,6 +124,8 @@ the Energy Saver panel.  There will be a checkbox labeled “Automatic graphics
 switching”, which should be disabled.  Otherwise, trying to run OpenMM may
 produce an error.  You will only see this option if your laptop has two GPUs
 
+.. _installing-on-linux:
+
 Installing on Linux
 *******************
 
@@ -126,7 +133,7 @@ Installing on Linux
 .zip file to expand it.
 
 2. Make sure you have Python 2.6 or higher (earlier versions will not work) and
-a C++ compiler (typically gcc or clang) installed on your computer.  You can
+a C++ compiler (typically :program:`gcc` or :program:`clang`) installed on your computer.  You can
 check what version of Python is installed by typing :code:`python` |--|\ :code:`version`
 into a console window.
 
@@ -140,7 +147,7 @@ into a console window.
 
 4. (Optional) If you plan to use the CPU platform, it is recommended that you
 install FFTW.  It is probably available through your system’s package manager
-such as :code:`yum` or :code:`apt-get`\ .  Alternatively, you can download
+such as :program:`yum` or :program:`apt-get`\ .  Alternatively, you can download
 it from http://www.fftw.org.  When configuring it, be sure to specify single
 precision and multiple threads (the |--|\ :code:`enable-float` and
 |--|\ :code:`enable-threads` options).  OpenMM will still work without FFTW, but the
@@ -150,7 +157,7 @@ performance of particle mesh Ewald (PME) will be much worse.
 ::
 
     cd <openmm_directory>
-    
+
 where :code:`<openmm_directory>` is the path to the OpenMM folder.  Then run
 the install script by typing
 ::
@@ -173,17 +180,17 @@ want to run OpenMM in another console window, you must type the above command in
 the new window.
 
 If you plan to use the CUDA platform, OpenMM also needs to locate the CUDA
-kernel compiler (nvcc).  By default it looks for it in the location
+kernel compiler (:program:`nvcc`).  By default it looks for it in the location
 :file:`/usr/local/cuda/bin/nvcc`.  If you have installed the CUDA toolkit in a different
-location, you can set OPENMM_CUDA_COMPILER to tell OpenMM where to find it.  For
+location, you can set :envvar:`OPENMM_CUDA_COMPILER` to tell OpenMM where to find it.  For
 example,
 ::
 
     export OPENMM_CUDA_COMPILER=/opt/CUDA/cuda-6.0/bin/nvcc
 
-7. Verify your installation by running the “testInstallation.py” script found in
-the “examples” folder of your OpenMM installation.  To run it, cd to the
-examples folder and type
+7. Verify your installation by running the :file:`testInstallation.py` script found in
+the :file:`examples` folder of your OpenMM installation.  To run it, :command:`cd` to the
+:file:`examples` folder and type
 ::
 
     python testInstallation.py
@@ -192,6 +199,7 @@ This script confirms that OpenMM is installed, checks whether GPU acceleration
 is available (via that OpenCL and/or CUDA platforms), and verifies that all
 platforms produce consistent results.
 
+.. _installing-on-windows:
 
 Installing on Windows
 *********************
@@ -234,11 +242,11 @@ PATH environment variable.  You may also need to add the Python executable to
 your PATH.
 
   * To find out if the Python executable is already in your PATH, open a command
-    prompt window by clicking on Start -> Programs -> Accessories -> Command Prompt.
-    (On Windows 7, select Start -> All Programs -> Accessories -> Command Prompt).
+    prompt window by clicking on :menuselection:`Start --> Programs --> Accessories --> Command Prompt`.
+    (On Windows 7, select :menuselection:`Start --> All Programs --> Accessories --> Command Prompt`).
     Type
     ::
-    
+
         python
 
     If you get an error message, such as "‘python’ is not recognized as an
@@ -252,11 +260,11 @@ your PATH.
     location.  You will need to enter it, along with the location of the OpenMM
     libraries, later in this process.
 
-  * Click on Start -> Control Panel -> System (On Windows 7, select Start ->
-    Control Panel -> System and Security -> System)
-  * Click on the “Advanced” tab or the “Advanced system settings” link
-  * Click “Environment Variables”
-  * Under “System variables,” select the line for “Path” and click “Edit…”
+  * Click on :menuselection:`Start --> Control Panel --> System` (On Windows 7, select :menuselection:`Start -->
+    Control Panel --> System and Security --> System`)
+  * Click on the :menuselection:`Advanced` tab or the :menuselection:`Advanced system settings` link
+  * Click :menuselection:`Environment Variables`
+  * Under :menuselection:`System variables`, select the line for :menuselection:`Path` and click :menuselection:`Edit…`
   * Add :file:`C:\\Program Files\\OpenMM\\lib` and :file:`C:\\Program Files\\OpenMM\\lib\\plugins`
     to the “Variable value”.  If you also need to add Python or FFTW to your
     PATH, enter their directory locations here.  Directory locations need to be
@@ -264,13 +272,13 @@ your PATH.
 
 
     If you installed OpenMM somewhere other than the default location, you must also
-    set OPENMM_PLUGIN_DIR to point to the plugins directory.  If this variable is
+    set :envvar:`OPENMM_PLUGIN_DIR` to point to the plugins directory.  If this variable is
     not set, it will assume plugins are in the default location (:file:`C:\\Program
     Files\\OpenMM\\lib\\plugins` or :file:`C:\\Program Files (x86)\\OpenMM\\lib\\plugins`).
 
-7. Verify your installation by running the “testInstallation.py” script found in
-the “examples” folder of your OpenMM installation.  To run it, open a command
-window, cd to the examples folder, and type
+7. Verify your installation by running the :file:`testInstallation.py` script found in
+the :file:`examples` folder of your OpenMM installation.  To run it, open a command
+window, :command:`cd` to the :file:`examples` folder, and type
 ::
 
     python testInstallation.py
@@ -279,7 +287,7 @@ This script confirms that OpenMM is installed, checks whether GPU acceleration
 is available (via that OpenCL and/or CUDA platforms), and verifies that all
 platforms produce consistent results.
 
-
+.. _running-simulations:
 
 Running Simulations
 ###################
@@ -290,9 +298,9 @@ A First Example
 ***************
 
 Let’s begin with our first example of an OpenMM script. It loads a PDB file
-called “input.pdb”, models it using the AMBER99SB force field and TIP3P water
+called :file:`input.pdb` that defines a biomolecular system, parameterizes it using the Amber99SB force field and TIP3P water
 model, energy minimizes it, simulates it for 10,000 steps with a Langevin
-integrator, and saves a frame to a PDB file called “output.pdb” every 1000 time
+integrator, and saves a snapshot frame to a PDB file called :file:`output.pdb` every 1000 time
 steps.
 
 .. samepage::
@@ -302,7 +310,7 @@ steps.
         from simtk.openmm import *
         from simtk.unit import *
         from sys import stdout
-        
+
         pdb = PDBFile('input.pdb')
         forcefield = ForceField('amber99sb.xml', 'tip3p.xml')
         system = forcefield.createSystem(pdb.topology, nonbondedMethod=PME,
@@ -320,10 +328,10 @@ steps.
 
         :autonumber:`Example,PDB example`
 
-You can find this script in the “examples” folder of your OpenMM installation.
-It is called “simulatePdb.py”.  To execute it from a command line, go to your
-terminal/console/command prompt window (see Chapter :ref:`installing-openmm`
-on setting up the window to use OpenMM).  Navigate to the “examples” folder by typing
+You can find this script in the :file:`examples` folder of your OpenMM installation.
+It is called :file:`simulatePdb.py`.  To execute it from a command line, go to your
+terminal/console/command prompt window (see Section :ref:`installing-openmm`
+on setting up the window to use OpenMM).  Navigate to the :file:`examples` folder by typing
 ::
 
     cd <examples_directory>
@@ -337,8 +345,8 @@ Then type
 
     python simulatePdb.py
 
-You can name your own scripts whatever you want, but their names should end with
-“.py”. Let’s go through the script line by line and see how it works.
+You can name your own scripts whatever you want.  Let’s go through the script line
+by line and see how it works.
 ::
 
     from simtk.openmm.app import *
@@ -353,25 +361,27 @@ start of your scripts.
 
     pdb = PDBFile('input.pdb')
 
-This line loads the PDB file from disk.  (The input.pdb file in the examples
+This line loads the PDB file from disk.  (The :file:`input.pdb` file in the :file:`examples`
 directory contains the villin headpiece in explicit solvent.)  More precisely,
-it creates a PDBFile object, passes the file name input.pdb to it as an
+it creates a :class:`PDBFile` object, passes the file name :file:`input.pdb` to it as an
 argument, and assigns the object to a variable called :code:`pdb`\ .  The
-PDBFile object contains the information that was read from the file: the
+:class:`PDBFile` object contains the information that was read from the file: the
 molecular topology and atom positions.  Your file need not be called
-“input.pdb”.  Feel free to change this line to specify any file you want.  Make
-sure you include the single quotes around the file name.
+:file:`input.pdb`.  Feel free to change this line to specify any file you want,
+though it must contain all of the atoms needed by the force field.
+(More information on how to add missing atoms and residues using OpenMM tools can be found in Chapter :ref:`model-building-and-editing`.)
+Make sure you include the single quotes around the file name.
 ::
 
     forcefield = ForceField('amber99sb.xml', 'tip3p.xml')
 
 This line specifies the force field to use for the simulation.  Force fields are
-defined by XML files.  Chapter :ref:`creating-force-fields` describes how to write these files,
-if you are interested in that sort of thing, but you probably won’t need to.  OpenMM
-includes XML files defining lots of standard force fields (see section :ref:`force-fields`).
-In this case we load two of those files: amber99sb.xml, which contains the
-AMBER99SB force field, and tip3p.xml, which contains the TIP3P water model.  The
-ForceField object is assigned to a variable called :code:`forcefield`\ .
+defined by XML files.  OpenMM includes XML files defining lots of standard force fields (see Section :ref:`force-fields`).
+If you find you need to extend the repertoire of force fields available,
+you can find more information on how to create these XML files in Section :ref:`creating-force-fields`.
+In this case we load two of those files: :file:`amber99sb.xml`, which contains the
+Amber99SB force field, and :file:`tip3p.xml`, which contains the TIP3P water model.  The
+:class:`ForceField` object is assigned to a variable called :code:`forcefield`\ .
 ::
 
     system = forcefield.createSystem(pdb.topology, nonbondedMethod=PME,
@@ -379,30 +389,38 @@ ForceField object is assigned to a variable called :code:`forcefield`\ .
 
 This line combines the force field with the molecular topology loaded from the
 PDB file to create a complete mathematical description of the system we want to
-simulate.  (More precisely, we invoke the ForceField object’s “createSystem”
-function.  It creates a System object, which we assign to the variable
+simulate.  (More precisely, we invoke the :class:`ForceField` object’s :meth:`.createSystem`
+function.  It creates a :class:`System` object, which we assign to the variable
 :code:`system`\ .)  It specifies some additional options about how to do that:
 use particle mesh Ewald for the long range electrostatic interactions
 (:code:`nonbondedMethod=PME`\ ), use a 1 nm cutoff for the direct space
 interactions (\ :code:`nonbondedCutoff=1*nanometer`\ ), and constrain the length
 of all bonds that involve a hydrogen atom (\ :code:`constraints=HBonds`\ ).
+Note the way we specified the cutoff distance 1 nm using :code:`1*nanometer`:
+This is an example of the powerful units tracking and automatic conversion facility
+built into the OpenMM Python API that makes specifying unit-bearing quantities
+convenient and less error-prone.  We could have equivalently specified
+:code:`10*angstrom` instead of :code:`1*nanometer` and achieved the same result,
+but had we specified the wrong dimensions, such as :code:`1*(nanometer**2)` or
+:code:`1*picoseconds`, OpenMM would have thrown an exception. 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)
 
 This line creates the integrator to use for advancing the equations of motion.
-It specifies a LangevinIntegrator, which (surprise!) performs Langevin dynamics,
+It specifies a :class:`LangevinIntegrator`, 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 (300K), the friction coefficient (1 ps\ :sup:`-1`\ ), and
+simulation temperature (300 K), the friction coefficient (1 ps\ :sup:`-1`\ ), and
 the step size (0.002 ps).
 ::
 
     simulation = Simulation(pdb.topology, system, integrator)
 
 This line combines the molecular topology, system, and integrator to begin a new
-simulation.  It creates a Simulation object and assigns it to a variable called
-\ :code:`simulation`\ .  A Simulation object coordinates all the processes
+simulation.  It creates a :class:`Simulation` object and assigns it to a variable called
+\ :code:`simulation`\ .  A :class:`Simulation` object manages all the processes
 involved in running a simulation, such as advancing time and writing output.
 ::
 
@@ -422,9 +440,9 @@ PDB file might produce very large forces.
     simulation.reporters.append(PDBReporter('output.pdb', 1000))
 
 This line creates a “reporter” to generate output during the simulation, and
-adds it to the Simulation object’s list of reporters.  A PDBReporter writes
+adds it to the :class:`Simulation` object’s list of reporters.  A :class:`PDBReporter` writes
 structures to a PDB file.  We specify that the output file should be called
-“output.pdb”, and that a structure should be written every 1000 time steps.
+:file:`output.pdb`, and that a structure should be written every 1000 time steps.
 ::
 
     simulation.reporters.append(StateDataReporter(stdout, 1000, step=True,
@@ -436,14 +454,18 @@ information every 1000 time steps: the current step index, the potential energy
 of the system, and the temperature.  We specify :code:`stdout` (not in
 quotes) as the output file, which means to write the results to the console.  We
 also could have given a file name (in quotes), just as we did for the
-PDBReporter, to write the information to a file.
+:class:`PDBReporter`, to write the information to a file.
 ::
 
     simulation.step(10000)
 
 Finally, we run the simulation, integrating the equations of motion for 10,000
 time steps.  Once it is finished, you can load the PDB file into any program you
-want for analysis and visualization (VMD, PyMol, AmberTools, etc.).
+want for analysis and visualization (VMD_, PyMol_, AmberTools_, etc.).
+
+.. _VMD: http://www.ks.uiuc.edu/Research/vmd/
+.. _PyMol: http://www.pymol.org
+.. _AmberTools: http://ambermd.org
 
 .. _using_amber_files:
 
@@ -452,10 +474,10 @@ Using AMBER Files
 
 OpenMM can build a system in several different ways.  One option, as shown
 above, is to start with a PDB file and then select a force field with which to
-model it.  Alternatively, you can use AmberTools to model your system.  In that
-case, you provide a prmtop file and an inpcrd file.  OpenMM loads the files and
-creates a system from them.  This is shown in the following script.  It can be
-found in OpenMM’s “examples” folder with the name “simulateAmber.py”.
+model it.  Alternatively, you can use AmberTools_ to model your system.  In that
+case, you provide a :class:`prmtop` file and an :class:`inpcrd` file.  OpenMM loads the files and
+creates a :class:`System` from them.  This is illustrated in the following script.  It can be
+found in OpenMM’s :file:`examples` folder with the name :file:`simulateAmber.py`.
 
 .. samepage::
     ::
@@ -464,7 +486,7 @@ found in OpenMM’s “examples” folder with the name “simulateAmber.py”.
         from simtk.openmm import *
         from simtk.unit import *
         from sys import stdout
-        
+
         prmtop = AmberPrmtopFile('input.prmtop')
         inpcrd = AmberInpcrdFile('input.inpcrd')
         system = prmtop.createSystem(nonbondedMethod=PME, nonbondedCutoff=1*nanometer,
@@ -472,6 +494,8 @@ found in OpenMM’s “examples” folder with the name “simulateAmber.py”.
         integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
         simulation = Simulation(prmtop.topology, system, integrator)
         simulation.context.setPositions(inpcrd.positions)
+        if inpcrd.boxVectors is not None:
+            simulation.context.setPeriodicBoxVectors(*inpcrd.boxVectors)
         simulation.minimizeEnergy()
         simulation.reporters.append(PDBReporter('output.pdb', 1000))
         simulation.reporters.append(StateDataReporter(stdout, 1000, step=True,
@@ -490,18 +514,27 @@ significant differences:
     inpcrd = AmberInpcrdFile('input.inpcrd')
 
 In these lines, we load the prmtop file and inpcrd file.  More precisely, we
-create AmberPrmtopFile and AmberInpcrdFile objects and assign them to the
+create :class:`AmberPrmtopFile` and :class:`AmberInpcrdFile` objects and assign them to the
 variables :code:`prmtop` and :code:`inpcrd`\ , respectively.  As before,
 you can change these lines to specify any files you want.  Be sure to include
 the single quotes around the file names.
+
+.. note::
+
+    The :class:`AmberPrmtopFile` reader provided by OpenMM only supports "new-style"
+    :file:`prmtop` files introduced in AMBER 7. The AMBER distribution still contains a number of
+    example files that are in the "old-style" :file:`prmtop` format. These "old-style" files will
+    not run in OpenMM.
+
+Next, the :class:`System` object is created in a different way:
 ::
 
     system = prmtop.createSystem(nonbondedMethod=PME, nonbondedCutoff=1*nanometer,
             constraints=HBonds)
 
-This line creates the system.  In the previous section, we loaded the topology
+In the previous section, we loaded the topology
 from a PDB file and then had the force field create a system based on it.  In
-this case, we don’t need a force field; the prmtop file already contains the
+this case, we don’t need a force field; the :file:`prmtop` file already contains the
 force field parameters, so it can create the system
 directly.
 ::
@@ -509,9 +542,24 @@ directly.
     simulation = Simulation(prmtop.topology, system, integrator)
     simulation.context.setPositions(inpcrd.positions)
 
-Notice that we now get the topology from the prmtop file and the atom positions
-from the inpcrd file.  In the previous section, both of these came from a PDB
-file, but AMBER puts the topology and positions in separate files.
+Notice that we now get the topology from the :file:`prmtop` file and the atom positions
+from the :file:`inpcrd` file.  In the previous section, both of these came from a PDB
+file, but AMBER puts the topology and positions in separate files.  We also add the
+following lines:
+::
+
+    if inpcrd.boxVectors is not None:
+        simulation.context.setPeriodicBoxVectors(*inpcrd.boxVectors)
+
+For periodic systems, the :file:`prmtop` file specifies the periodic box vectors, just
+as a PDB file does.  When we call :meth:`createSystem`, it sets those as the default
+periodic box vectors, to be used automatically for all simulations.  However, the
+:file:`inpcrd` may *also* specify periodic box vectors,
+and if so we want to use those ones instead.  For example, if the system has been
+equilibrated with a barostat, the box vectors may have changed during equilibration.
+We therefore check to see if the :file:`inpcrd` file contained box vectors.  If so,
+we call :meth:`setPeriodicBoxVectors` to tell it to use those ones, overriding the
+default ones provided by the :class:`System`.
 
 .. _using_gromacs_files:
 
@@ -519,10 +567,10 @@ Using Gromacs Files
 *******************
 
 A third option for creating your system is to use the Gromacs setup tools.  They
-produce a gro file containing the coordinates and a top file containing the
+produce a :file:`gro` file containing the coordinates and a :file:`top` file containing the
 topology.  OpenMM can load these exactly as it did the AMBER files.  This is
-shown in the following script.  It can be found in OpenMM’s “examples” folder
-with the name “simulateGromacs.py”.
+shown in the following script.  It can be found in OpenMM’s :file:`examples` folder
+with the name :file:`simulateGromacs.py`.
 
 .. samepage::
     ::
@@ -531,7 +579,7 @@ with the name “simulateGromacs.py”.
         from simtk.openmm import *
         from simtk.unit import *
         from sys import stdout
-        
+
         gro = GromacsGroFile('input.gro')
         top = GromacsTopFile('input.top', unitCellDimensions=gro.getUnitCellDimensions(),
                 includeDir='/usr/local/gromacs/share/gromacs/top')
@@ -551,37 +599,82 @@ with the name “simulateGromacs.py”.
         :autonumber:`Example,Gromacs example`
 
 This script is nearly identical to the previous one, just replacing
-AmberInpcrdFile and AmberPrmtopFile with GromacsGroFile and GromacsTopFile.
-Note that when we create the GromacsTopFile, we specify values for two extra
+:class:`AmberInpcrdFile` and :class:`AmberPrmtopFile` with :class:`GromacsGroFile` and :class:`GromacsTopFile`.
+Note that when we create the :class:`GromacsTopFile`, we specify values for two extra
 options.  First, we specify
 :code:`unitCellDimensions=gro.getUnitCellDimensions()`\ .  Unlike OpenMM and
-AMBER, which store the periodic unit cell dimensions with the topology, Gromacs
-stores them with the coordinates.  To let GromacsTopFile create a Topology
+AMBER, which can store periodic unit cell dimensions with the topology, Gromacs
+only stores them with the coordinates.  To let :class:`GromacsTopFile` create a :class:`Topology`
 object, we therefore need to tell it the unit cell dimensions that were loaded
-from the gro file.  You only need to do this if you are simulating a periodic
+from the :file:`gro` file.  You only need to do this if you are simulating a periodic
 system.  For implicit solvent simulations, it usually can be omitted.
 
 Second, we specify :code:`includeDir='/usr/local/gromacs/share/gromacs/top'`\ .  Unlike AMBER,
-which stores all the force field parameters directly in a prmtop file, Gromacs just stores
+which stores all the force field parameters directly in a :file:`prmtop` file, Gromacs just stores
 references to force field definition files that are installed with the Gromacs
 application.  OpenMM needs to know where to find these files, so the
 :code:`includeDir` parameter specifies the directory containing them.  If you
-omit this parameter, OpenMM will assume the default location :file:`/usr/local/gromacs/share/gromacs/top`, 
+omit this parameter, OpenMM will assume the default location :file:`/usr/local/gromacs/share/gromacs/top`,
 which is often where they are installed on
 Unix-like operating systems.  So in :numref:`Example,Gromacs example` we actually could have omitted
 this parameter, but if the Gromacs files were installed in any other location,
 we would need to include it.
 
+.. _using-charmm-files:
+
+Using CHARMM Files
+******************
+
+Yet another option is to load files created by the CHARMM setup tools, or other compatible
+tools such as VMD.  Those include a :file:`psf` file containing topology information, and an
+ordinary PDB file for the atomic coordinates.  (Coordinates can also be loaded from CHARMM
+coordinate or restart files using the :class:`CharmmCrdFile` and :class:`CharmmRstFile` classes).  In addition,
+you must provide a set of files containing the force
+field definition to use.  This can involve several different files with varying formats and
+filename extensions such as :file:`par`, :file:`prm`, :file:`top`, :file:`rtf`, :file:`inp`,
+and :file:`str`.  To do this, load all the definition files into a :class:`CharmmParameterSet`
+object, then include that object as the first parameter when you call :meth:`createSystem`
+on the :class:`CharmmPsfFile`.
+
+.. samepage::
+    ::
+
+        from simtk.openmm.app import *
+        from simtk.openmm import *
+        from simtk.unit import *
+        from sys import stdout, exit, stderr
+
+        psf = CharmmPsfFile('input.psf')
+        pdb = PDBFile('input.pdb')
+        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)
+        simulation = Simulation(psf.topology, system, integrator)
+        simulation.context.setPositions(pdb.positions)
+        simulation.minimizeEnergy()
+        simulation.reporters.append(PDBReporter('output.pdb', 1000))
+        simulation.reporters.append(StateDataReporter(stdout, 1000, step=True,
+                potentialEnergy=True, temperature=True))
+        simulation.step(10000)
+
+    .. caption::
+
+        :autonumber:`Example,CHARMM example`
+
+Note that both the CHARMM and XPLOR versions of the :file:`psf` file format are supported.
+
 .. _the-script-builder-application:
 
 The Script Builder Application
 ******************************
 
 One option for writing your own scripts is to start with one of the examples
-given above (the one in section :ref:`a-first-example` if you are starting from a PDB file, section
-:ref:`using_amber_files` if you are starting from AMBER prmtop and inpcrd files, or section
-:ref:`using_gromacs_files` if you are starting from Gromacs gro and top files), then customize it
-to suit your needs.  Another option is to use the OpenMM Script Builder application.
+given above (the one in Section :ref:`a-first-example` if you are starting from a PDB file, section
+:ref:`using_amber_files` if you are starting from AMBER :file:`prmtop` and :file:`inpcrd` files, section
+:ref:`using_gromacs_files` if you are starting from Gromacs :file:`gro` and :file:`top` files, or section
+:ref:`using-charmm-files` if you are starting from CHARMM files), then customize it
+to suit your needs.  Another option is to use the `OpenMM Script Builder`_ application.
 
 
 .. figure:: ../images/ScriptBuilder.png
@@ -594,9 +687,11 @@ This is a web application available at https://builder.openmm.org.  It provides
 a graphical interface with simple choices for all the most common simulation
 options, then automatically generates a script based on them.  As you change the
 settings, the script is instantly updated to reflect them.  Once everything is
-set the way you want, click the “Save Script” button to save it to disk, or
+set the way you want, click the :menuselection:`Save Script` button to save it to disk, or
 simply copy and paste it into a text editor.
 
+.. _`OpenMM Script Builder`: https://builder.openmm.org
+
 .. _simulation-parameters:
 
 Simulation Parameters
@@ -607,23 +702,22 @@ Now let’s consider lots of ways you might want to customize your script.
 Platforms
 =========
 
-
-When creating a Simulation, you can optionally tell it what Platform to use.
-OpenMM includes four platforms: Reference, CPU, CUDA, and OpenCL.  For a
+When creating a :class:`Simulation`, you can optionally tell it what :class:`Platform` to use.
+OpenMM includes four platforms: :class:`Reference`, :class:`CPU`, :class:`CUDA`, and :class:`OpenCL`.  For a
 description of the differences between them, see Section :ref:`platforms`.  If you do not
-specify a Platform, it will select one automatically.  Usually its choice will
+specify a :class:`Platform`, it will select one automatically.  Usually its choice will
 be reasonable, but you may want to change it.
 
-The following lines specify to use the CUDA Platform:
+The following lines specify to use the :class:`CUDA` platform:
 ::
 
     platform = Platform.getPlatformByName('CUDA')
     simulation = Simulation(prmtop.topology, system, integrator, platform)
 
-The Platform name should be :code:`OpenCL`\ , :code:`CUDA`\ , :code:`CPU`\, or
-:code:`Reference`\ .
+The platform name should be one of :code:`OpenCL`, :code:`CUDA`, :code:`CPU`, or
+:code:`Reference`.
 
-You also can specify Platform-specific properties that customize how
+You also can specify platform-specific properties that customize how
 calculations should be done.  See Chapter :ref:`platform-specific-properties` for details of the
 properties that each Platform supports.  For example, the following lines specify to parallelize
 work across two different GPUs (CUDA devices 0 and 1), doing all computations in
@@ -654,12 +748,12 @@ For the main force field, OpenMM provides the following options:
 =============================  ================================================================================
 File                           Force Field                                                                     
 =============================  ================================================================================
-:code:`amber96.xml`            AMBER96\ :cite:`Kollman1997`
-:code:`amber99sb.xml`          AMBER99\ :cite:`Wang2000` with modified backbone torsions\ :cite:`Hornak2006`
-:code:`amber99sbildn.xml`      AMBER99SB plus improved side chain torsions\ :cite:`Lindorff-Larsen2010`
-:code:`amber99sbnmr.xml`       AMBER99SB with modifications to fit NMR data\ :cite:`Li2010`
-:code:`amber03.xml`            AMBER03\ :cite:`Duan2003`
-:code:`amber10.xml`            AMBER10
+:code:`amber96.xml`            Amber96\ :cite:`Kollman1997`
+:code:`amber99sb.xml`          Amber99\ :cite:`Wang2000` with modified backbone torsions\ :cite:`Hornak2006`
+:code:`amber99sbildn.xml`      Amber99SB plus improved side chain torsions\ :cite:`Lindorff-Larsen2010`
+:code:`amber99sbnmr.xml`       Amber99SB with modifications to fit NMR data\ :cite:`Li2010`
+:code:`amber03.xml`            Amber03\ :cite:`Duan2003`
+:code:`amber10.xml`            Amber10 (documented in the AmberTools_ manual as `ff10`)
 :code:`amoeba2009.xml`         AMOEBA 2009\ :cite:`Ren2002`.  This force field is deprecated.  It is 
                                recommended to use AMOEBA 2013 instead.
 :code:`amoeba2013.xml`         AMOEBA 2013\ :cite:`Shi2013`
@@ -700,10 +794,10 @@ the following files:
 =========================  =================================================================================================
 File                       Implicit Solvation Model                                                                      
 =========================  =================================================================================================
-:code:`amber96_obc.xml`    GBSA-OBC solvation model\ :cite:`Onufriev2004` for use with AMBER96 force field
-:code:`amber99_obc.xml`    GBSA-OBC solvation model for use with AMBER99 force fields
-:code:`amber03_obc.xml`    GBSA-OBC solvation model for use with AMBER03 force field
-:code:`amber10_obc.xml`    GBSA-OBC solvation model for use with AMBER10 force field
+:code:`amber96_obc.xml`    GBSA-OBC solvation model\ :cite:`Onufriev2004` for use with Amber96 force field
+:code:`amber99_obc.xml`    GBSA-OBC solvation model for use with Amber99 force fields
+:code:`amber03_obc.xml`    GBSA-OBC solvation model for use with Amber03 force field
+:code:`amber10_obc.xml`    GBSA-OBC solvation model for use with Amber10 force field
 :code:`amoeba2009_gk.xml`  Generalized Kirkwood solvation model\ :cite:`Schnieders2007` for use with AMOEBA 2009 force field
 :code:`amoeba2013_gk.xml`  Generalized Kirkwood solvation model for use with AMOEBA 2013 force field
 =========================  =================================================================================================
@@ -726,7 +820,7 @@ produce an error since no water parameters are defined:
 Be aware that some force fields and water models include "extra particles", such
 as lone pairs or Drude particles.  Examples include the CHARMM polarizable force
 field and all of the 4 and 5 site water models.  To use these force fields, you
-must first add the extra particles to the Topology.  See section
+must first add the extra particles to the :class:`Topology`.  See section
 :ref:`adding-or-removing-extra-particles` for details.
 
 AMBER Implicit Solvent
@@ -740,7 +834,7 @@ with the :code:`implicitSolvent` parameter:
 
     system = prmtop.createSystem(implicitSolvent=OBC2)
 
-OpenMM supports most of the implicit solvent models used by AMBER.  Here are the
+OpenMM supports all of the Generalized Born models used by AMBER.  Here are the
 allowed values for :code:`implicitSolvent`\ :
 
 .. tabularcolumns:: |l|L|
@@ -752,7 +846,7 @@ Value          Meaning
 :code:`HCT`    Hawkins-Cramer-Truhlar GBSA model\ :cite:`Hawkins1995` (corresponds to igb=1 in AMBER)                                                                                                                         
 :code:`OBC1`   Onufriev-Bashford-Case GBSA model\ :cite:`Onufriev2004` using the GB\ :sup:`OBC`\ I parameters (corresponds to igb=2 in AMBER).                                                                                
 :code:`OBC2`   Onufriev-Bashford-Case GBSA model\ :cite:`Onufriev2004` using the GB\ :sup:`OBC`\ II parameters (corresponds to igb=5 in AMBER).
-               This is the same model used by the GBSA-OBC files described in section :ref:`force-fields`.
+               This is the same model used by the GBSA-OBC files described in Section :ref:`force-fields`.
 :code:`GBn`    GBn solvation model\ :cite:`Mongan2007` (corresponds to igb=7 in AMBER).                                                                                                                                       
 :code:`GBn2`   GBn2 solvation model\ :cite:`Nguyen2013` (corresponds to igb=8 in AMBER).                                                                                                                                      
 =============  ==================================================================================================================================
@@ -762,7 +856,7 @@ You can further control the solvation model in a few ways.  First, you can
 specify the dielectric constants to use for the solute and solvent:
 ::
 
-    system = prmtop.createSystem(implicitSolvent=OBC2, soluteDielectric=2.0,
+    system = prmtop.createSystem(implicitSolvent=OBC2, soluteDielectric=1.0,
             solventDielectric=80.0)
 
 If they are not specified, the solute and solvent dielectrics default to 1.0 and
@@ -771,7 +865,7 @@ are slightly different from those used elsewhere in OpenMM: when building a
 system from a force field, the solvent dielectric defaults to 78.3.
 
 You also can model the effect of a non-zero salt concentration by specifying the
-Debye screening parameter:
+Debye-Huckel screening parameter\ :cite:`Srinivasan1999`:
 ::
 
     system = prmtop.createSystem(implicitSolvent=OBC2, implicitSolventKappa=1.0/nanometer)
@@ -850,7 +944,7 @@ Specifying the Polarization Method
 OpenMM allows the setting of several other parameters particular to the AMOEBA
 force field.  The :code:`mutualInducedTargetEpsilon` option allows you to
 specify the accuracy to which the induced dipoles are calculated at each time
-step; the default value is 0.00001.  The :code:`polarization` setting
+step; the default value is 0.01.  The :code:`polarization` setting
 determines whether the calculation of the induced dipoles is continued until the
 dipoles are self-consistent to within the tolerance specified by
 :code:`mutualInducedTargetEpsilon` or whether a quick estimate of the induced
@@ -876,7 +970,7 @@ Implicit Solvent and Solute Dielectrics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 For implicit solvent simulations using the AMOEBA force field, the
-'amoeba2009_gk.xml' file should be included in the initialization of the force
+:file:`amoeba2013_gk.xml` file should be included in the initialization of the force
 field:
 ::
 
@@ -897,7 +991,7 @@ Constraints
 ===========
 
 
-When creating the system (either from a force field or a prmtop file), you can
+When creating the system (either from a force field or an AMBER :file:`prmtop` file), you can
 optionally tell OpenMM to constrain certain bond lengths and angles.  For
 example,
 ::
@@ -920,7 +1014,7 @@ Value             Meaning
 
 The main reason to use constraints is that it allows one to use a larger
 integration time step.  With no constraints, one is typically limited to a time
-step of about 1 fs.  With :code:`HBonds` constraints, this can be increased
+step of about 1 fs for typical biomolecular force fields like AMBER or CHARMM.  With :code:`HBonds` constraints, this can be increased
 to about 2 fs.  With :code:`HAngles`\ , it can be further increased to 3.5 or
 4 fs.
 
@@ -934,11 +1028,15 @@ disable this behavior with the :code:`rigidWater` parameter:
 Be aware that flexible water may require you to further reduce the integration
 step size, typically to about 0.5 fs.
 
+.. note::
+
+   The AMOEBA forcefield is intended to be used without constraints.
+
 Heavy Hydrogens
 ===============
 
 
-When creating the system (either from a force field or a prmtop file), you can
+When creating the system (either from a force field or an AMBER :file:`prmtop` file), you can
 optionally tell OpenMM to increase the mass of hydrogen atoms.  For example,
 ::
 
@@ -965,7 +1063,7 @@ In the examples of the previous sections, we used Langevin integration:
 
     integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
 
-The three parameter values in this line are the simulation temperature (300K),
+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
 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
@@ -991,7 +1089,7 @@ Brownian (diffusive) dynamics can be used by specifying the following:
 
     integrator = BrownianIntegrator(300*kelvin, 1/picosecond, 0.002*picoseconds)
 
-The parameters are the same as for Langevin dynamics: temperature (300K),
+The parameters are the same as for Langevin dynamics: temperature (300 K),
 friction coefficient (1 ps\ :sup:`-1`\ ), and step size (0.002 ps).
 
 Variable Time Step Langevin Integrator
@@ -1037,8 +1135,7 @@ integrator (as shown in the examples above) is usually the best way to do it.
 OpenMM does provide an alternative, however: you can use a Verlet integrator,
 then add an Andersen thermostat to your system to provide temperature coupling.
 
-To do this, add a single line to the script as shown below.  (The lines in grey
-are just for context.)
+To do this, we can add an :class:`AndersenThermostat` object to the :class:`System` as shown below.
 ::
 
     ...
@@ -1048,7 +1145,7 @@ are just for context.)
     integrator = VerletIntegrator(0.002*picoseconds)
     ...
 
-The two parameters of the Andersen thermostat are the temperature (300K) and
+The two parameters of the Andersen thermostat are the temperature (300 K) and
 collision frequency (1 ps\ :sup:`-1`\ ).
 
 Pressure Coupling
@@ -1069,7 +1166,7 @@ previous section:
     ...
 
 The parameters of the Monte Carlo barostat are the pressure (1 bar) and
-temperature (300K).  The barostat assumes the simulation is being run at
+temperature (300 K).  The barostat assumes the simulation is being run at
 constant temperature, but it does not itself do anything to regulate the
 temperature.
 
@@ -1137,7 +1234,8 @@ Removing Center of Mass Motion
 ==============================
 
 
-By default, OpenMM removes all center of mass motion at every time step so the
+By default, :class:`System` objects created with the OpenMM application tools add
+a :class:`CMMotionRemover` that removes all center of mass motion at every time step so the
 system as a whole does not drift with time.  This is almost always what you
 want.  In rare situations, you may want to allow the system to drift with time.
 You can do this by specifying the :code:`removeCMMotion` parameter when you
@@ -1151,19 +1249,22 @@ Writing Trajectories
 ====================
 
 
-OpenMM can save simulation trajectories to disk in two formats: PDB and DCD.
+OpenMM can save simulation trajectories to disk in two formats: PDB_ and DCD_.
 Both of these are widely supported formats, so you should be able to read them
 into most analysis and visualization programs.
 
+.. _PDB: http://www.wwpdb.org/documentation/format33/v3.3.html
+.. _DCD: http://www.ks.uiuc.edu/Research/vmd/plugins/molfile/dcdplugin.html
+
 To save a trajectory, just add a “reporter” to the simulation, as shown in the
 example scripts above:
 ::
 
     simulation.reporters.append(PDBReporter('output.pdb', 1000))
 
-The two parameters of the PDBReporter are the output filename and how often (in
+The two parameters of the :class:`PDBReporter` are the output filename and how often (in
 number of time steps) output structures should be written.  To use DCD format,
-just replace “PDBReporter” with “DCDReporter”.  The parameters represent the
+just replace :class:`PDBReporter` with :class:`DCDReporter`.  The parameters represent the
 same values:
 ::
 
@@ -1175,7 +1276,7 @@ Recording Other Data
 
 In addition to saving a trajectory, you may want to record other information
 over the course of a simulation, such as the potential energy or temperature.
-OpenMM provides a reporter for this purpose also.  Create a StateDataReporter
+OpenMM provides a reporter for this purpose also.  Create a :class:`StateDataReporter`
 and add it to the simulation:
 ::
 
@@ -1205,22 +1306,23 @@ separated by spaces instead of commas:
     simulation.reporters.append(StateDataReporter('data.txt', 1000, progress=True,
             temperature=True, totalSteps=10000, separator=' '))
 
+.. _model-building-and-editing:
 
 Model Building and Editing
 ##########################
 
 Sometimes you have a PDB file that needs some work before you can simulate it.
 Maybe it doesn’t contain hydrogen atoms (which is common for structures
-determined by x-ray crystallography), so you need to add them.  Or perhaps you
+determined by X-ray crystallography), so you need to add them.  Or perhaps you
 want to simulate the system in explicit water, but the PDB file doesn’t contain
 water molecules.  Or maybe it does contain water molecules, but they contain the
 wrong number of interaction sites for the water model you want to use.  OpenMM’s
 Modeller class can fix problems such as these.
 
-To use it, create a Modeller object, providing the initial Topology and atom
+To use it, create a :class:`Modeller` object, providing the initial :class:`Topology` and atom
 positions.  You then can invoke various modelling functions on it.  Each one
-modifies the system in some way, creating a new Topology and list of positions.
-When you are all done, you can retrieve them from the Modeller and use them as
+modifies the system in some way, creating a new :class:`Topology` and list of positions.
+When you are all done, you can retrieve them from the :class:`Modeller` and use them as
 the starting point for your simulation:
 
 .. samepage::
@@ -1243,7 +1345,7 @@ Now let’s consider the particular functions you can call.
 Adding Hydrogens
 ****************
 
-Call the addHydrogens function to add missing hydrogen atoms:
+Call the :meth:`addHydrogens` function to add missing hydrogen atoms:
 ::
 
     modeller.addHydrogens(forcefield)
@@ -1274,7 +1376,7 @@ documentation for the Modeller class.
 Adding Solvent
 **************
 
-Call addSolvent to create a box of solvent (water and ions) around the model:
+Call :meth:`addSolvent` to create a box of solvent (water and ions) around the model:
 ::
 
     modeller.addSolvent(forcefield)
@@ -1284,7 +1386,7 @@ molecule comes closer to any solute atom than the sum of their van der Waals
 radii.  It also determines the charge of the solute, and adds enough positive or
 negative ions to make the system neutral.
 
-When called as shown above, addSolvent expects that periodic box dimensions were
+When called as shown above, :meth:`addSolvent` expects that periodic box dimensions were
 specified in the PDB file, and it uses them as the size for the water box.  If
 your PDB file does not specify a box size, or if you want to use a different
 size, you can specify one:
@@ -1303,14 +1405,14 @@ then creates a cubic box of width (solute size)+2*(padding).  The above line
 guarantees that no part of the solute comes closer than 1 nm to any edge of the
 box.
 
-By default, addSolvent creates TIP3P water molecules, but it also supports other
+By default, :meth:`addSolvent` creates TIP3P water molecules, but it also supports other
 water models:
 ::
 
     modeller.addSolvent(forcefield, model='tip5p')
 
-Allowed values for the :code:`model` option are 'tip3p', 'tip3pfb', 'spce', 
-'tip4pew', 'tip4pfb', and 'tip5p'.  Be sure to include the single quotes 
+Allowed values for the :code:`model` option are ``'tip3p'``, ``'tip3pfb'``, ``'spce'``,
+``'tip4pew'``, ``'tip4pfb'``, and ``'tip5p'``.  Be sure to include the single quotes
 around the value.
 
 Another option is to add extra ion pairs to give a desired total ionic strength.
@@ -1331,9 +1433,9 @@ options.  For example, this creates a potassium chloride solution:
 
     modeller.addSolvent(forcefield, ionicStrength=0.1*molar, positiveIon='K+')
 
-Allowed values for :code:`positiveIon` are 'Cs+', 'K+', 'Li+', 'Na+', and
-'Rb+'.  Allowed values for :code:`negativeIon` are 'Cl-', 'Br-', 'F-', and
-'I-'.  Be sure to include the single quotes around the value.  Also be aware
+Allowed values for :code:`positiveIon` are ``'Cs+'``, ``'K+'``, ``'Li+'``, ``'Na+'``, and
+``'Rb+'``.  Allowed values for :code:`negativeIon` are ``'Cl-'``, ``'Br-'``, ``'F-'``, and
+``'I-'``.  Be sure to include the single quotes around the value.  Also be aware
 some force fields do not include parameters for all of these ion types, so you
 need to use types that are supported by your chosen force field.
 
@@ -1345,7 +1447,7 @@ Adding or Removing Extra Particles
 “Extra particles” are particles that do not represent ordinary atoms.  This
 includes the virtual interaction sites used in many water models, Drude
 particles, etc.  If you are using a force field that involves extra particles,
-you must add them to the Topology.  To do this, call:
+you must add them to the :class:`Topology`.  To do this, call:
 ::
 
     modeller.addExtraParticles(forcefield)
@@ -1370,10 +1472,10 @@ Saving The Results
 ******************
 
 Once you have finished editing your model, you can immediately use the resulting
-Topology and atom positions as the input to a Simulation.  If you plan to
+:class:`Topology` object and atom positions as the input to a :class:`Simulation`.  If you plan to
 simulate it many times, though, it is usually better to save the result to a new
 PDB file, then use that as the input for the simulations.  This avoids the cost
-of repeating the modeling operations at the start of every simulation, and also
+of repeating the modelling operations at the start of every simulation, and also
 ensures that all your simulations are really starting from exactly the same
 structure.
 
@@ -1387,7 +1489,7 @@ PDB file.
         from simtk.openmm.app import *
         from simtk.openmm import *
         from simtk.unit import *
-        
+
         print('Loading...')
         pdb = PDBFile('input.pdb')
         forcefield = ForceField('amber99sb.xml', 'tip3p.xml')
@@ -1419,7 +1521,7 @@ In the previous chapter, we looked at some basic scripts for running simulations
 and saw lots of ways to customize them.  If that is all you want to do—run
 straightforward molecular simulations—you already know everything you need to
 know.  Just use the example scripts and customize them in the ways described in
-section :ref:`simulation-parameters`.
+Section :ref:`simulation-parameters`.
 
 OpenMM can do far more than that.  Your script has the full OpenMM API at its
 disposal, along with all the power of the Python language and libraries.  In
@@ -1432,18 +1534,18 @@ your own.
 Starting in this section, we will assume some knowledge of programming, as well
 as familiarity with the OpenMM API.  Consult the OpenMM Users Guide and API
 documentation if you are uncertain about how something works.   You can also use
-the Python “help” command.  For example,
+the Python :code:`help` command.  For example,
 ::
 
     help(Simulation)
 
-will print detailed documentation on the Simulation class.
+will print detailed documentation on the :class:`Simulation` class.
 
 Simulated Annealing
 *******************
 
 Here is a very simple example of how to do simulated annealing.  The following
-lines linearly reduce the temperature from 300K to 0K in 100 increments,
+lines linearly reduce the temperature from 300 K to 0 K in 100 increments,
 executing 1000 time steps at each temperature:
 
 .. samepage::
@@ -1461,7 +1563,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 LangevinIntegrator and then
+time through, it adjusts the temperature of the :class:`LangevinIntegrator` and then
 calls :code:`step(1000)` to take 1000 time steps.
 
 Applying an External Force to Particles: a Spherical Container
@@ -1472,13 +1574,13 @@ spherical container with radius 2 nm.  We implement the container by applying a
 harmonic potential to every particle:
 
 .. math::
-    \begin{array}{lll}
-    E(r) = & 0          & r\le2\\
-           & 100(r-2)^2 & r>2
-    \end{array}
+    E(r) = \begin{cases}
+           0          & r\le2\\
+           100(r-2)^2 & r>2
+           \end{cases}
 
 where *r* is the distance of the particle from the origin, measured in nm.
-We can easily do this using OpenMM’s CustomExternalForce class.  This class
+We can easily do this using OpenMM’s :class:`CustomExternalForce` class.  This class
 applies a force to some or all of the particles in the system, where the energy
 is an arbitrary function of each particle’s (\ *x*\ , *y*\ , *z*\ )
 coordinates.  Here is the code to do it:
@@ -1500,39 +1602,39 @@ coordinates.  Here is the code to do it:
 
         :autonumber:`Example,spherical container`
 
-The first thing it does is create a CustomExternalForce object and add it to the
-System.  The argument to CustomExternalForce is a mathematical expression
-specifying the energy of each particle.  This can be any function of *x*\ ,
+The first thing it does is create a :class:`CustomExternalForce` object and add it to the
+:class:`System`.  The argument to :class:`CustomExternalForce` is a mathematical expression
+specifying the potential energy of each particle.  This can be any function of *x*\ ,
 *y*\ , and *z* you want.  It also can depend on global or per-particle
 parameters.  A wide variety of restraints, steering forces, shearing forces,
 etc. can be implemented with this method.
 
 Next it must specify which particles to apply the force to.  In this case, we
 want it to affect every particle in the system, so we loop over them and call
-:code:`addParticle()` once for each one.  The two arguments are the index of
+:meth:`addParticle` once for each one.  The two arguments are the index of
 the particle to affect, and the list of per-particle parameter values (an empty
 list in this case).  If we had per-particle parameters, such as to make the
 force stronger for some particles than for others, this is where we would
 specify them.
 
-Notice that we do all of this immediately after creating the System.  That is
+Notice that we do all of this immediately after creating the :class:`System`.  That is
 not an arbitrary choice.
 
 .. warning::
 
-    If you add new forces to a System, you must do so before creating the Simulation.
-    Once you create a Simulation, modifying the System will have no effect on that Simulation.
+    If you add new forces to a :class:`System`, you must do so before creating the :class:`Simulation`.
+    Once you create a :class:`Simulation`, modifying the :class:`System` will have no effect on that :class:`Simulation`.
 
 Extracting and Reporting Forces (and other data)
 ************************************************
 
-OpenMM provides reporters for two output formats: PDB and DCD.  Both of those
+OpenMM provides reporters for two output formats: PDB_ and DCD_.  Both of those
 formats store only positions, not velocities, forces, or other data.  In this
 section, we create a new reporter that outputs forces.  This illustrates two
 important things: how to write a reporter, and how to query the simulation for
 forces or other data.
 
-Here is the definition of the ForceReporter class:
+Here is the definition of the :class:`ForceReporter` class:
 
 .. samepage::
     ::
@@ -1552,7 +1654,7 @@ Here is the definition of the ForceReporter class:
             def report(self, simulation, state):
                 forces = state.getForces().value_in_unit(kilojoules/mole/nanometer)
                 for f in forces:
-                    print >>self._out, f[0], f[1], f[2]
+                    self._out.write('%g %g %g\n' % (f[0], f[1], f[2]))
 
     .. caption::
 
@@ -1564,8 +1666,8 @@ should generate reports.  It opens the output file for writing and records the
 reporting interval.  The destructor closes the file.
 
 We then have two methods that every reporter must implement:
-:code:`describeNextReport()` and :code:`report()`\ .  A Simulation object
-periodically calls :code:`describeNextReport()` on each of its reporters to
+:meth:`describeNextReport()` and :meth:`report()`.  A Simulation object
+periodically calls :meth:`describeNextReport()` on each of its reporters to
 find out when that reporter will next generate a report, and what information
 will be needed to generate it.  The return value should be a five element tuple,
 whose elements are as follows:
@@ -1580,12 +1682,12 @@ whose elements are as follows:
 * Whether the next report will need energies.
 
 
-When the time comes for the next scheduled report, the Simulation calls
-:code:`report()` to generate the report.  The arguments are the Simulation
-object, and a State that is guaranteed to contain all the information that was
-requested by :code:`describeNextReport()`\ .  A State object contains a
+When the time comes for the next scheduled report, the :class:`Simulation` calls
+:meth:`report()` to generate the report.  The arguments are the :class:`Simulation`
+object, and a :class:`State` that is guaranteed to contain all the information that was
+requested by :meth:`describeNextReport()`\ .  A State object contains a
 snapshot of information about the simulation, such as forces or particle
-positions.  We call :code:`getForces()` to retrieve the forces and convert
+positions.  We call :meth:`getForces()` to retrieve the forces and convert
 them to the units we want to output (kJ/mole/nm).  Then we loop over each value
 and write it to the file.  To keep the example simple, we just print the values
 in text format, one line per particle.  In a real program, you might choose a
@@ -1606,8 +1708,8 @@ This example illustrates a different sort of analysis.  Instead of running a
 simulation, assume we have already identified a set of structures we are
 interested in.  These structures are saved in a set of PDB files.  We want to
 loop over all the files in a directory, load them in one at a time, and compute
-the potential energy of each one.  Assume we have already created our System and
-Simulation.  The following lines perform the analysis:
+the potential energy of each one.  Assume we have already created our :class:`System` and
+:class:`Simulation`.  The following lines perform the analysis:
 
 .. samepage::
     ::
@@ -1624,9 +1726,9 @@ Simulation.  The following lines perform the analysis:
         :autonumber:`Example,computing energies`
 
 We use Python’s :code:`listdir()` function to list all the files in the
-directory.  We create a PDBFile object for each one and call
-:code:`setPositions()` on the Context to specify the particle positions loaded
-from the PDB file.  We then compute the energy by calling :code:`getState()`
+directory.  We create a :class:`PDBFile` object for each one and call
+:meth:`setPositions()` on the Context to specify the particle positions loaded
+from the PDB file.  We then compute the energy by calling :meth:`getState()`
 with the option :code:`getEnergy=True`\ , and print it to the console along
 with the name of the file.
 

docs-source/usersguide/conf.py

@@ -190,6 +190,9 @@ latex_elements = {
             {code}{\\small{}\\texttt{#2}\\normalsize{}}%
         }[\\PackageError{DUspan}{Unrecognized option passed to DUspan: #1}{}]%
     }%""",
+
+# Omit the index.
+'printindex': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples

docs-source/usersguide/index.rst

@@ -7,8 +7,9 @@ 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
+Contributors:  Kyle Beauchamp, Christopher Bruns, John Chodera, Peter Eastman, Mark
+Friedrichs, Joy P. Ku, Tom Markland, Vijay Pande, Randy Radmer, Michael Sherman,
+Jason Swails, Lee-Ping Wang
 
 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,

docs-source/usersguide/library.rst

@@ -1803,17 +1803,17 @@ The OpenCL Platform recognizes the following Platform-specific properties:
   “single”, nearly all calculations are done in single precision.  This is the
   fastest option but also the least accurate.  If it is set to “mixed”, forces are
   computed in single precision but integration is done in double precision.  This
-  gives much better energy conservation with only a slightly decrease in speed.
+  gives much better energy conservation with only a slight decrease in speed.
   If it is set to “double”, all calculations are done in double precision.  This
   is the most accurate option, but is usually much slower than the others.
-* OpenCLUseCpuPme: This selects whether to use the CPU based PME
+* OpenCLUseCpuPme: This selects whether to use the CPU-based PME
   implementation.  The allowed values are “true” or “false”.  Depending on your
   hardware, this might (or might not) improve performance.  To use this option,
   you must have FFTW (single precision, multithreaded) installed, and your CPU
   must support SSE 4.1.
 * OpenCLPlatformIndex: When multiple OpenCL implementations are installed on
-  your computer, this is used to select which one to use.  The value is the zero-
-  based index of the platform (in the OpenCL sense, not the OpenMM sense) to use,
+  your computer, this is used to select which one to use.  The value is the
+  zero-based index of the platform (in the OpenCL sense, not the OpenMM sense) to use,
   in the order they are returned by the OpenCL platform API.  This is useful, for
   example, in selecting whether to use a GPU or CPU based OpenCL implementation.
 * OpenCLDeviceIndex: When multiple OpenCL devices are available on your
@@ -1842,10 +1842,10 @@ The CUDA Platform recognizes the following Platform-specific properties:
   “single”, nearly all calculations are done in single precision.  This is the
   fastest option but also the least accurate.  If it is set to “mixed”, forces are
   computed in single precision but integration is done in double precision.  This
-  gives much better energy conservation with only a slightly decrease in speed.
+  gives much better energy conservation with only a slight decrease in speed.
   If it is set to “double”, all calculations are done in double precision.  This
   is the most accurate option, but is usually much slower than the others.
-* CudaUseCpuPme: This selects whether to use the CPU based PME implementation.
+* CudaUseCpuPme: This selects whether to use the CPU-based PME implementation.
   The allowed values are “true” or “false”.  Depending on your hardware, this
   might (or might not) improve performance.  To use this option, you must have
   FFTW (single precision, multithreaded) installed, and your CPU must support SSE
@@ -1873,7 +1873,7 @@ The CUDA Platform recognizes the following Platform-specific properties:
   synchronizes between the CPU and GPU.  If this is set to “true” (the default),
   CUDA will allow the calling thread to sleep while the GPU is performing a
   computation, allowing the CPU to do other work.  If it is set to “false”, CUDA
-  will spin-lock while the GPU is working.  This can improve performance slightly,
+  will spin-lock while the GPU is working.  Setting it to "false" can improve performance slightly,
   but also prevents the CPU from doing anything else while the GPU is working.
 
 
@@ -1978,7 +1978,7 @@ cases in which the C++ behavior cannot be directly mapped into C. These
 interface and helper functions are compiled in to the main OpenMM library so
 there is nothing special you have to do to get access to them.
 
-In the /\ :code:`include` subdirectory of your OpenMM installation directory,
+In the :code:`include` subdirectory of your OpenMM installation directory,
 there is a machine-generated header file :code:`OpenMMCWrapper.h` that
 should be #included in any C program that is to make calls to OpenMM functions.
 That header contains declarations for all the OpenMM C interface functions and
@@ -2008,7 +2008,7 @@ constructor                 new OpenMM::ClassName()                    | OpenMM_
 destructor                  | OpenMM::ClassName* thing;                | OpenMM_ClassName* thing;
                             | delete thing;                            | OpenMM_ClassName_destroy(thing);
 class method                | OpenMM::ClassName* thing;                | OpenMM_ClassName* thing;
-                            | thing->someName(args);                   | OpenMM_ClassName_someName(thing, args)
+                            | thing->method(args);                     | OpenMM_ClassName_method(thing, args)
 Boolean (type & constants)  | bool                                     | OpenMM_Boolean
                             | true, false                              | OpenMM_True(1), OpenMM_False(0)
 string                      std::string                                char*
@@ -2085,12 +2085,12 @@ conceptually since it differs slightly for each kind of object.
 =======================================================  =========================================================================================================================================================================================================
 Function                                                 Operation
 =======================================================  =========================================================================================================================================================================================================
-*Thing*\ Array\* create(int size)                        Create a heap-allocated array of *Things*\ , with space pre-allocated to hold :code:`size` of them. You can start at :code:`size`\ ==0 if you want since these arrays are dynamically resizeable.
+*Thing*\ Array\* create(int size)                        Create a heap-allocated array of *Things*\ , with space pre-allocated to hold :code:`size` of them. You can start at :code:`size==0` if you want since these arrays are dynamically resizeable.
 void destroy(\ *Thing*\ Array\*)                         Free the heap space that is currently in use for the passed-in array of *Things*\ .
-int getSize(\ *Thing*\ Array\*)                          Return the current number of *Things* in this array. This means you can :code:`get()` and :code:`set()` elements up to :code:`getSize()`\ -1.
+int getSize(\ *Thing*\ Array\*)                          Return the current number of *Things* in this array. This means you can :code:`get()` and :code:`set()` elements up to :code:`getSize()-1`\ .
 void resize(\ *Thing*\ Array\*, int size)                Change the size of this array to the indicated value which may be smaller or larger than the current size. Existing elements remain in their same locations as long as they still fit.
 void append(\ *Thing*\ Array\*, *Thing*\ )               Add a *Thing* to the end of the array, increasing the array size by one. The precise syntax depends on the actual type of *Thing*\ ; see below.
-void set(\ *Thing*\ Array\*, int index, *Thing*\ )       Store a copy of *Thing* in the indicated element of the array (indexed from 0). The array must be of length at least :code:`index`\ +1; you can’t grow the array with this function.
+void set(\ *Thing*\ Array\*, int index, *Thing*\ )       Store a copy of *Thing* in the indicated element of the array (indexed from 0). The array must be of length at least :code:`index+1`\ ; you can’t grow the array with this function.
 *Thing* get(\ *Thing*\ Array\*, int index)               Retrieve a particular element from the array (indexed from 0). (For some Things the value is returned in arguments rather than as the function return.)
 =======================================================  =========================================================================================================================================================================================================
 
@@ -2212,15 +2212,15 @@ special you have to do to get access to them.
 
 Because Fortran is case-insensitive, calls to Fortran subroutines (however
 capitalized) are mapped by the compiler into all-lowercase or all-uppercase
-names, and different compilers use different conventions. The automatically-
-generated OpenMM Fortran “wrapper” subroutines, which are generated in C and
+names, and different compilers use different conventions. The automatically-generated
+OpenMM Fortran “wrapper” subroutines, which are generated in C and
 thus case-sensitive, are provided in two forms for compatibility with the
 majority of Fortran compilers, including Intel Fortran and gfortran. The two
 forms are: (1) all-lowercase with a trailing underscore, and (2) all-uppercase
 without a trailing underscore. So regardless of the Fortran compiler you are
 using, it should find a suitable subroutine to call in the main OpenMM library.
 
-In the :code:`/include` subdirectory of your OpenMM installation directory,
+In the :code:`include` subdirectory of your OpenMM installation directory,
 there is a machine-generated module file :code:`OpenMMFortranModule.f90`
 that must be compiled along with any Fortran program that is to make calls to
 OpenMM functions. (You can look at the :code:`Makefile` or Visual Studio
@@ -2260,7 +2260,7 @@ constructor                 new OpenMM::ClassName()              | type (OpenMM_
 destructor                  | OpenMM::ClassName* thing;          | type (OpenMM_ClassName) thing
                             | delete thing;                      | call OpenMM_ClassName_destroy(thing)
 class method                | OpenMM::ClassName* thing;          | type (OpenMM_ClassName) thing
-                            | thing->someName(args*)             | call OpenMM_ClassName_someName(thing, args)
+                            | thing->method(args*)               | call OpenMM_ClassName_method(thing, args)
 Boolean (type & constants)  | bool                               | integer*4
                             | true                               | parameter (OpenMM_True=1)
                             | false                              | parameter (OpenMM_False=0)
@@ -2282,8 +2282,8 @@ OpenMM_Vec3 helper type
 =======================
 
 Unlike the other OpenMM objects which are opaque and manipulated via pointers,
-the Fortran API uses an ordinary :code:`real`\ :code:`*8(3)` array in
-place of the :code:`OpenMM::Vec3` type. The
+the Fortran API uses an ordinary :code:`real*8(3)` array in
+place of the :code:`OpenMM::Vec3` type.
 You can work directly with the individual elements of this type from your
 Fortran program if you want. For convenience, a :code:`scale()` function is
 provided that creates a new Vec3 from an old one and a scale factor:
@@ -2561,7 +2561,9 @@ notable differences:
 
     myContext.getState(getEnergy=True, getForce=False, …)
     
-#. Wherever the C++ API uses references to return multiple values from a method, the Python API returns a tuple.  For example, in C++ you would query a HarmonicBondForce for a bond’s parameters as follows:
+#. Wherever the C++ API uses references to return multiple values from a method,
+   the Python API returns a tuple.  For example, in C++ you would query a
+   HarmonicBondForce for a bond’s parameters as follows:
    ::
 
     int particle1, particle2;
@@ -2574,8 +2576,8 @@ notable differences:
     [particle1, particle2, length, k] = f.getBondParameters(i)
 
 #. Unlike C++, the Python API accepts and returns quantities with units attached
-   to most values (see the “Units and dimensional analysis” section below for
-   details).  In short, this means that while values in C++ have *implicit*\
+   to most values (see Section :ref:`units-and-dimensional-analysis` below for
+   details).  In short, this means that while values in C++ have *implicit*
    units, the Python API returns objects that have values and *explicit* units.
 
 
@@ -2614,6 +2616,9 @@ nanometers.  We could just as easily specify it in different units:
 
 The use of units in OpenMM is discussed in the next section.
 
+
+.. _units-and-dimensional-analysis:
+
 Units and dimensional analysis
 ==============================
 
@@ -2706,6 +2711,9 @@ multiply operator (‘*’) or the explicit Quantity constructor:
     # or more verbosely
     bond_length = Quantity(value=1.53, unit=nanometer)
 
+When working with Numpy arrays you *must* use the explicit constructor.  You cannot
+multiply them by a unit, because the Numpy array class overloads the multiply operator.
+
 
 Arithmetic with units
 ---------------------
@@ -2844,22 +2852,22 @@ in and out.
 ::
 
     >>> a = Vec3(1,2,3) * nanometers
-    >>> print a
+    >>> print(a)
     (1, 2, 3) nm
-    >>> print a.in_units_of(angstroms)
+    >>> print(a.in_units_of(angstroms))
     (10.0, 20.0, 30.0) A
 
     >>> s2 = [[1,2,3],[4,5,6]] * centimeter
-    >>> print s2
+    >>> print(s2)
     [[1, 2, 3], [4, 5, 6]] cm
-    >>> print s2 / millimeter
+    >>> print(s2/millimeter)
     [[10.0, 20.0, 30.0], [40.0, 50.0, 60.0]]
 
     >>> import numpy
     >>> a = Quantity(numpy.array([1,2,3]), centimeter)
-    >>> print a
+    >>> print(a)
     [1 2 3] cm
-    >>> print a / millimeter
+    >>> print(a/millimeter)
     [ 10.  20.  30.]
 
 Converting a whole list to different units at once is much faster than
@@ -2869,13 +2877,13 @@ Angstroms:
 ::
 
     for v in state.getPositions():
-        print v.value_in_unit(angstrom)
+        print(v.value_in_unit(angstrom))
 
 This can be rewritten as follows:
 ::
 
     for v in state.getPositions().value_in_unit(angstrom):
-        print v
+        print(v)
 
 The two versions produce identical results, but the second one will run faster,
 and therefore is preferred.
@@ -2893,8 +2901,8 @@ GROMACS is a large, complex application written primarily in C.  The
 considerations involved in adapting it to use OpenMM are likely to be similar to
 those faced by developers of other existing applications.
 
-The first principle we followed in adapting GROMACS was to keep all OpenMM-
-related code isolated to just a few files, while modifying as little of the
+The first principle we followed in adapting GROMACS was to keep all OpenMM-related
+code isolated to just a few files, while modifying as little of the
 existing GROMACS code as possible.  This minimized the risk of breaking existing
 parts of the code, while making the OpenMM-related parts as easy to work with as
 possible.  It also minimized the need for C code to invoke the C++ API.  (This
@@ -3563,9 +3571,9 @@ the ring polymer representing each particle is directly related to its De
 Broglie thermal wavelength (uncertainty in its position).
 
 RPMD calculations must be converged with respect to the number *n* of beads
-used.  Each bead is evolved at the effective temperature *nT*\ , where *T*\
+used.  Each bead is evolved at the effective temperature *nT*\ , where *T*
 is the temperature for which properties are required.  The number of beads
-needed to converge a calculation can be estimated using\ :cite:`Markland2008`\
+needed to converge a calculation can be estimated using\ :cite:`Markland2008`
 
 
 .. math::

docs-source/usersguide/references.bib

@@ -378,6 +378,16 @@
    type = {Journal Article}
 }
 
+@article{Srinivasan1999
+   author = {Srinivasan, J and Trevathan, M. W. and Beroza, P. and Case, D. A.},
+   title = {Application of a pairwise generalized {Born} model to proteins and nucleic acids: inclusion of salt effects},
+   journal = {Theor. Chem. Acc.},
+   volume = {101},
+   pages = {426-434},
+   year = {1999},
+   type = {Journal Article}
+}
+
 @article{Thole1981
    author = {Thole, B. T.},
    title = {Molecular polarizabilities calculated with a modified dipole interaction},

docs-source/usersguide/theory.rst

@@ -20,7 +20,7 @@ On the other hand, many details are intentionally left unspecified.  Any
 behavior that is not specified either in this guide or in the API documentation
 is left up to the Platform, and may be implemented in different ways by
 different Platforms.  For example, an Integrator is required to produce a
-trajectory that satisfies constraints to within the user specified tolerance,
+trajectory that satisfies constraints to within the user-specified tolerance,
 but the algorithm used to enforce those constraints is left up to the Platform.
 Similarly, this guide provides the functional form of each Force, but does not
 specify what level of numerical precision it must be calculated to.
@@ -131,7 +131,7 @@ Each torsion is represented by an energy term of the form
 
 
 where :math:`\theta` is the dihedral angle formed by the four particles, :math:`\theta_0`
-is the equilibrium angle, *n* is the periodicity, and *k* is
+is the phase offset, *n* is the periodicity, and *k* is
 the force constant.
 
 RBTorsionForce
@@ -164,7 +164,7 @@ Each torsion pair is represented by an energy term of the form
 
 
 where :math:`\theta_1` and :math:`\theta_2` are the two dihedral angles
-coupled by the term, and *f*\ (\ *x*\ ,\ *y*\ ) is defined by a user supplied
+coupled by the term, and *f*\ (\ *x*\ ,\ *y*\ ) is defined by a user-supplied
 grid of tabulated values.  A natural cubic spline surface is fit through the
 tabulated values, then evaluated to determine the energy for arbitrary (\ :math:`\theta_1`\ ,
 :math:`\theta_2`\ ) pairs.
@@ -205,7 +205,7 @@ second derivatives at both ends
 
 When an exception has been added for a pair of particles, :math:`\sigma` and :math:`\epsilon`
 are the parameters specified by the exception.  Otherwise they are determined
-from the parameters of the individual particles using the Lorentz-Bertelot
+from the parameters of the individual particles using the Lorentz-Berthelot
 combining rule:
 
 .. math::
@@ -458,14 +458,14 @@ between particles *i* and *j*\ .  :math:`f_\text{GB}(d_{ij}, R_i, R_j)` is defin
 
 
 .. math::
-   {f}_{\text{GB}}\left({d}_{ij},{R}_{i},{R}_{j}\right)={\left[{d}_{{ij}^{2}}+{R}_{i}{R}_{j}\text{exp}\left(\frac{-{d}_{ij}}{{4R}_{i}{R}_{j}}\right)\right]}^{1/2}
+   {f}_{\text{GB}}\left({d}_{ij},{R}_{i},{R}_{j}\right)={\left[{d}_{ij}^2+{R}_{i}{R}_{j}\text{exp}\left(\frac{-{d}_{ij}^2}{{4R}_{i}{R}_{j}}\right)\right]}^{1/2}
 
 
 :math:`R_i` is the Born radius of particle *i*\ , which calculated as
 
 
 .. math::
-   R_i=\frac{1}{\rho_i^{-1}-r_i^{-1}\text{tanh}\left(\alpha \Psi_{i}-{\beta \Psi}_{{i}^{2}}+{\gamma \Psi}_{{i}^{3}}\right)}
+   R_i=\frac{1}{\rho_i^{-1}-r_i^{-1}\text{tanh}\left(\alpha \Psi_{i}-{\beta \Psi}_i^2+{\gamma \Psi}_i^3\right)}
 
 
 where :math:`\alpha`, :math:`\beta`, and :math:`\gamma` are the GB\ :sup:`OBC`\ II parameters :math:`\alpha` = 1, :math:`\beta` = 0.8, and :math:`\gamma` =
@@ -497,70 +497,6 @@ its Born radius, and :math:`r_\mathit{solvent}` is the solvent radius, which is
 to be 0.14 nm.
 
 
-
-GBVIForce
-*********
-
-The GBVI force is an implicit solvent force based on an algorithm developed by
-Paul Labute.\ :cite:`Labute2008` The GBVI force is currently undergoing
-testing to validate that it is correctly implementing the algorithm. The GBVI
-energy is given by Equation 2 of the referenced paper:
-
-
-.. math::
-   E=-\frac{1}{2}\left(\frac{1}{{\epsilon }_{\mathit{solute}}}-\frac{1}{{\epsilon }_{\mathit{solvent}}}\right)\sum _{i,j}\frac{{q}_{i}{q}_{j}}{{f}_{\text{GB}}\left({d}_{ij},{R}_{i},{R}_{j}\right)}+\sum _{i}^{n}{\gamma }_{i}{\left(\frac{{r}_{i}}{{R}_{i}}\right)}^{3}
-
-
-where the indices *i* and *j* run over all n particles, :math:`\epsilon_\mathit{solute}`
-and :math:`\epsilon_\mathit{solvent}` are the dielectric constants of the solute
-and solvent respectively, :math:`q_i` is the charge of particle *i*\ ,
-:math:`d_{ij}` is the distance between particles *i* and *j*\ , :math:`r_i`
-are the input particle radii, and the :math:`\gamma_i` are adjustable
-parameters. :math:`f_\text{GB}(d_{ij}, R_i, R_j)` is
-defined as above (Section :ref:`gbsaobcforce`) for the GBSAOBCForce. The Born radii, :math:`R_i`, are defined by the equation
-
-
-.. math::
-   {R}_{i}={\left[{r}_{i}^{-3}-\sum _{j}^{n}V\left({d}_{ij},{r}_{i},{S}_{j}\right)\right]}^{-\frac{1}{3}}
-
-
-where V(d,r,S) is given by
-
-
-.. math::
-   V\left(d,r,S\right)=\left\{\begin{array}{ccc}L\left(d,x,S\right){\mid }_{x=\mathrm{max}\left(r,d-S\right)}^{x=d+S}& \mid r-S\mid <d& \\ 0& 0\le d\le r-S& \\ L\left(d,x,S\right){\mid }_{x=d-S}^{x=d+S}& 0\le d\le S-r& \end{array}\right\}
-
-
-and
-
-
-.. math::
-   L\left(d,x,S\right)=\frac{3}{2}\left[\frac{1}{4{dx}^{2}}-\frac{1}{{3x}^{3}}+\frac{{d}^{2}-{S}^{2}}{8{dx}^{4}}\right]
-
-
-The S\ :sub:`i` are derived from the covalent topology of the solute:
-
-
-.. math::
-   {S}_{i}=0\text{.}\text{95}\cdot\mathrm{max}\left(0,\nu_i^{1/3}\right)
-
-
-
-.. math::
-   {\nu}_{i}={r}_{i}^{3}-\frac{1}{8}\sum _{j}{a}_{ij}^{2}\left({3r}_{i}-{a}_{ij}\right)+{a}_{ji}^{2}\left({3r}_{j}-{a}_{ji}\right)
-
-
-and
-
-
-.. math::
-   {a}_{ij}=\frac{{r}_{j}^{2}-({r}_{i}-{d}_{ij}{)}^{2}}{{2d}_{ij}}
-
-
-where :math:`d_{ij}` is the fixed covalent bond length between particles *i* and
-*j*\ , and the sum in the calculation of the :math:`\nu_i` is over the particles *j*
-covalently bonded to particle *i*.
-
 AndersenThermostat
 ******************
 
@@ -622,7 +558,7 @@ weight function
 
 
 where :math:`\Delta E` is the change in potential energy resulting from the step,
-\ *P* is the system pressure, *N* is the number of molecules in the
+\ *P* is the pressure being applied to the system, *N* is the number of molecules in the
 system, :math:`k_B` is Boltzmann’s constant, and *T* is the system
 temperature.  In particular, if :math:`\Delta W\le 0` the step is always accepted.
 If :math:`\Delta W > 0`\ , the step is accepted with probability
@@ -1136,7 +1072,7 @@ VariableVerletIntegrator
 
 This is very similar to VerletIntegrator, but instead of using the same step
 size for every time step, it continuously adjusts the step size to keep the
-integration error below a user specified tolerance.  It compares the positions
+integration error below a user-specified tolerance.  It compares the positions
 generated by Verlet integration with those that would be generated by an
 explicit Euler integrator, and takes the difference between them as an estimate
 of the integration error:
@@ -1161,7 +1097,7 @@ specified error tolerance:
 
 
 where :math:`\delta` is the error tolerance.  This is the largest step that may be
-taken consistent with the user specified accuracy requirement.
+taken consistent with the user-specified accuracy requirement.
 
 (Note that the integrator may sometimes choose to use a smaller value for :math:`\Delta t`
 than given above.  For example, it might restrict how much the step size

docs/C++ API Reference.html

-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
-<html>
-<head>
-<meta http-equiv="REFRESH" content="0;url=api-c++/index.html"></HEAD>
-<BODY>
-</BODY>
-</HTML>
\ No newline at end of file

docs/CMakeLists.txt

-#
-# Build and install API documentation
-#
-
-find_package(Doxygen QUIET)
-mark_as_advanced(CLEAR DOXYGEN_EXECUTABLE)
-IF(DOXYGEN_EXECUTABLE)
-    # Generate C++ API documentation
-
-    SET(DOXY_CONFIG_C++ "${CMAKE_BINARY_DIR}/DoxyfileC++")
-    CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/DoxyfileC++.in 
-          ${DOXY_CONFIG_C++}
-          @ONLY )
-    FILE(GLOB_RECURSE OPENMM_INCLUDES "openmm/include/*.h")
-    FILE(GLOB_RECURSE OLLA_INCLUDES "olla/include/*.h")
-    ADD_CUSTOM_COMMAND(
-        OUTPUT "${CMAKE_BINARY_DIR}/api-c++/index.html"
-        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXY_CONFIG_C++}
-        DEPENDS ${OPENMM_INCLUDES} ${OLLA_INCLUDES}
-        WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
-        COMMENT "Generating C++ API documentation using Doxygen")
-    ADD_CUSTOM_TARGET(C++ApiDocs 
-        DEPENDS "${CMAKE_BINARY_DIR}/api-c++/index.html"
-        COMMENT "Generating C++ API documentation using Doxygen"
-        SOURCES 
-            "${CMAKE_CURRENT_SOURCE_DIR}/DoxyfileC++.in"
-            ${OPENMM_INCLUDES}
-            ${OLLA_INCLUDES}
-    ) 
-    FILE(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/api-c++/")
-    INSTALL(DIRECTORY "${PROJECT_BINARY_DIR}/api-c++/"
-            DESTINATION "docs/api-c++/")
-    INSTALL(FILES "C++ API Reference.html"
-            DESTINATION "docs/")
-    ADD_CUSTOM_TARGET(DoxygenApiDocs
-        DEPENDS "${CMAKE_BINARY_DIR}/api-c++/index.html"
-        COMMENT "Generating C++ API documentation using Doxygen"
-        SOURCES 
-        "${CMAKE_CURRENT_SOURCE_DIR}/DoxyfileC++.in"
-        "${CMAKE_CURRENT_SOURCE_DIR}/DoxyfilePython.in"
-        ${OPENMM_INCLUDES}
-        ${OLLA_INCLUDES}
-    )
-    set(OPENMM_GENERATE_API_DOCS OFF CACHE BOOL "Whether to create API documentation using Doxygen")
-    IF (OPENMM_GENERATE_API_DOCS)
-        SET_TARGET_PROPERTIES(DoxygenApiDocs PROPERTIES EXCLUDE_FROM_ALL FALSE)
-    ENDIF (OPENMM_GENERATE_API_DOCS)
-
-    # Generate Python API documentation
-
-    IF (OPENMM_BUILD_PYTHON_WRAPPERS)
-        SET(DOXY_CONFIG_PYTHON "${CMAKE_BINARY_DIR}/DoxyfilePython")
-        CONFIGURE_FILE(${CMAKE_CURRENT_SOURCE_DIR}/DoxyfilePython.in 
-            ${DOXY_CONFIG_PYTHON}
-            @ONLY )
-        ADD_CUSTOM_COMMAND(
-            OUTPUT "${CMAKE_BINARY_DIR}/api-python/index.html"
-            COMMAND ${DOXYGEN_EXECUTABLE} ${DOXY_CONFIG_PYTHON}
-            DEPENDS RunSwig
-            WORKING_DIRECTORY "${CMAKE_BINARY_DIR}"
-            COMMENT "Generating Python API documentation using Doxygen")
-        ADD_CUSTOM_TARGET(PythonApiDocs 
-            DEPENDS "${CMAKE_BINARY_DIR}/api-python/index.html"
-            COMMENT "Generating Python API documentation using Doxygen"
-            SOURCES 
-                "${CMAKE_CURRENT_SOURCE_DIR}/DoxyfilePython.in"
-                ${OPENMM_INCLUDES}
-                ${OLLA_INCLUDES}
-        ) 
-        FILE(MAKE_DIRECTORY "${PROJECT_BINARY_DIR}/api-python/")
-        INSTALL(DIRECTORY "${PROJECT_BINARY_DIR}/api-python/"
-                DESTINATION "docs/api-python/")
-        INSTALL(FILES "Python API Reference.html"
-                DESTINATION "docs/")
-        ADD_DEPENDENCIES(DoxygenApiDocs PythonApiDocs)
-    ENDIF (OPENMM_BUILD_PYTHON_WRAPPERS)
-ENDIF(DOXYGEN_EXECUTABLE)
-
-
-#
-# Build and install the User Guide and Developer Guide
-#
-
-SET(SPHINX_BUILD_DIR "${CMAKE_BINARY_DIR}/sphinx-docs/")
-FILE(MAKE_DIRECTORY "${SPHINX_BUILD_DIR}")
-
-ADD_CUSTOM_COMMAND(
-    OUTPUT "${SPHINX_BUILD_DIR}/userguide/latex/OpenMMUsersGuide.pdf"
-    COMMAND "${CMAKE_MAKE_PROGRAM}" BUILDDIR="${SPHINX_BUILD_DIR}/userguide" OPENMM_VERSION="${OPENMM_MAJOR_VERSION}.${OPENMM_MINOR_VERSION}" latexpdf
-    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/usersguide"
-    COMMENT "Generating PDF user guide"
-)
-ADD_CUSTOM_COMMAND(
-    OUTPUT "${SPHINX_BUILD_DIR}/developerguide/latex/OpenMMDeveloperGuide.pdf"
-    COMMAND "${CMAKE_MAKE_PROGRAM}" BUILDDIR="${SPHINX_BUILD_DIR}/developerguide" OPENMM_VERSION="${OPENMM_MAJOR_VERSION}.${OPENMM_MINOR_VERSION}" latexpdf
-    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/developerguide"
-    COMMENT "Generating PDF developer guide"
-)
-ADD_CUSTOM_TARGET(sphinxpdf
-    DEPENDS "${SPHINX_BUILD_DIR}/userguide/latex/OpenMMUsersGuide.pdf" "${SPHINX_BUILD_DIR}/developerguide/latex/OpenMMDeveloperGuide.pdf"
-)
-
-ADD_CUSTOM_COMMAND(
-    OUTPUT "${SPHINX_BUILD_DIR}/userguide/html/index.html"
-    COMMAND "${CMAKE_MAKE_PROGRAM}" BUILDDIR="${SPHINX_BUILD_DIR}/userguide" OPENMM_VERSION="${OPENMM_MAJOR_VERSION}.${OPENMM_MINOR_VERSION}" html
-    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/usersguide"
-    COMMENT "Generating PDF user guide"
-)
-ADD_CUSTOM_COMMAND(
-    OUTPUT "${SPHINX_BUILD_DIR}/developerguide/html/index.html"
-    COMMAND "${CMAKE_MAKE_PROGRAM}" BUILDDIR="${SPHINX_BUILD_DIR}/developerguide" OPENMM_VERSION="${OPENMM_MAJOR_VERSION}.${OPENMM_MINOR_VERSION}" html
-    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/developerguide"
-    COMMENT "Generating PDF developer guide"
-)
-ADD_CUSTOM_TARGET(sphinxhtml
-    DEPENDS "${SPHINX_BUILD_DIR}/userguide/html/index.html" "${SPHINX_BUILD_DIR}/developerguide/html/index.html"
-)
-
-install(FILES "${SPHINX_BUILD_DIR}/userguide/latex/OpenMMUsersGuide.pdf" "${SPHINX_BUILD_DIR}developerguide/latex/OpenMMDeveloperGuide.pdf"
-    DESTINATION docs/)
-
-FILE(GLOB LICENSE_FILES "licenses/*.txt")
-install(FILES ${LICENSE_FILES}
-    DESTINATION licenses/)

docs/DoxyfileC++.in

-# Doxyfile 1.5.3
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-DOXYFILE_ENCODING      = UTF-8
-PROJECT_NAME           = @PROJECT_NAME@
-PROJECT_NUMBER         = 
-OUTPUT_DIRECTORY       = 
-CREATE_SUBDIRS         = NO
-OUTPUT_LANGUAGE        = English
-BRIEF_MEMBER_DESC      = YES
-REPEAT_BRIEF           = YES
-ABBREVIATE_BRIEF       = 
-ALWAYS_DETAILED_SEC    = NO
-INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = NO
-STRIP_FROM_PATH        = 
-STRIP_FROM_INC_PATH    = 
-SHORT_NAMES            = NO
-JAVADOC_AUTOBRIEF      = YES
-QT_AUTOBRIEF           = NO
-MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = YES
-INHERIT_DOCS           = YES
-SEPARATE_MEMBER_PAGES  = NO
-TAB_SIZE               = 4
-ALIASES                = 
-OPTIMIZE_OUTPUT_FOR_C  = NO
-OPTIMIZE_OUTPUT_JAVA   = NO
-BUILTIN_STL_SUPPORT    = NO
-CPP_CLI_SUPPORT        = NO
-DISTRIBUTE_GROUP_DOC   = YES
-SUBGROUPING            = YES
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL            = YES
-EXTRACT_PRIVATE        = NO
-EXTRACT_STATIC         = NO
-EXTRACT_LOCAL_CLASSES  = YES
-EXTRACT_LOCAL_METHODS  = NO
-EXTRACT_ANON_NSPACES   = NO
-HIDE_UNDOC_MEMBERS     = NO
-HIDE_UNDOC_CLASSES     = NO
-HIDE_FRIEND_COMPOUNDS  = NO
-HIDE_IN_BODY_DOCS      = YES
-INTERNAL_DOCS          = NO
-CASE_SENSE_NAMES       = YES
-HIDE_SCOPE_NAMES       = YES
-SHOW_INCLUDE_FILES     = YES
-INLINE_INFO            = YES
-SORT_MEMBER_DOCS       = YES
-SORT_BRIEF_DOCS        = NO
-SORT_BY_SCOPE_NAME     = NO
-GENERATE_TODOLIST      = YES
-GENERATE_TESTLIST      = YES
-GENERATE_BUGLIST       = YES
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS       = 
-MAX_INITIALIZER_LINES  = 30
-SHOW_USED_FILES        = YES
-SHOW_DIRECTORIES       = YES
-FILE_VERSION_FILTER    =
-SHOW_NAMESPACES        = NO
-SHOW_FILES             = NO
-SHOW_DIRECTORIES       = NO
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET                  = NO
-WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
-WARN_IF_DOC_ERROR      = YES
-WARN_NO_PARAMDOC       = NO
-WARN_FORMAT            = "$file:$line: $text    "
-WARN_LOGFILE           = 
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT                  = "@CMAKE_SOURCE_DIR@/openmmapi" \
-                         "@CMAKE_SOURCE_DIR@/olla" \
-                         "@CMAKE_SOURCE_DIR@/serialization/include/openmm/serialization/XmlSerializer.h" \
-                         "@CMAKE_SOURCE_DIR@/plugins/drude/openmmapi/include" \
-                         "@CMAKE_SOURCE_DIR@/plugins/rpmd/openmmapi/include" \
-                         "@CMAKE_SOURCE_DIR@/plugins/amoeba/openmmapi/include"
-INPUT_ENCODING         = UTF-8
-FILE_PATTERNS          = 
-RECURSIVE              = YES
-EXCLUDE                = 
-EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       = */tests/* \
-                         */openmmapi/src/* \
-                         */.svn/* \
-                         */olla/include/openmm/kernels.h \
-                         */DrudeKernels.h \
-                         */RpmdKernels.h \
-                         */amoebaKernels.h \
-EXCLUDE_SYMBOLS        = 
-EXAMPLE_PATH           = 
-EXAMPLE_PATTERNS       = 
-EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             = 
-INPUT_FILTER           = 
-FILTER_PATTERNS        = 
-FILTER_SOURCE_FILES    = NO
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER         = NO
-INLINE_SOURCES         = NO
-STRIP_CODE_COMMENTS    = YES
-REFERENCED_BY_RELATION = YES
-REFERENCES_RELATION    = YES
-REFERENCES_LINK_SOURCE = YES
-USE_HTAGS              = NO
-VERBATIM_HEADERS       = YES
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX     = NO
-COLS_IN_ALPHA_INDEX    = 5
-IGNORE_PREFIX          = 
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML          = YES
-HTML_OUTPUT            = api-c++
-HTML_FILE_EXTENSION    = .html
-HTML_HEADER            = 
-HTML_FOOTER            = 
-HTML_STYLESHEET        = 
-HTML_ALIGN_MEMBERS     = YES
-GENERATE_HTMLHELP      = NO
-HTML_DYNAMIC_SECTIONS  = YES
-CHM_FILE               = 
-HHC_LOCATION           = 
-GENERATE_CHI           = NO
-BINARY_TOC             = NO
-TOC_EXPAND             = NO
-DISABLE_INDEX          = NO
-ENUM_VALUES_PER_LINE   = 4
-GENERATE_TREEVIEW      = YES
-TREEVIEW_WIDTH         = 250
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX         = NO
-LATEX_OUTPUT           = latex
-LATEX_CMD_NAME         = latex
-MAKEINDEX_CMD_NAME     = makeindex
-COMPACT_LATEX          = NO
-PAPER_TYPE             = a4wide
-EXTRA_PACKAGES         = 
-LATEX_HEADER           = 
-PDF_HYPERLINKS         = NO
-USE_PDFLATEX           = NO
-LATEX_BATCHMODE        = NO
-LATEX_HIDE_INDICES     = NO
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    = 
-RTF_EXTENSIONS_FILE    = 
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN           = NO
-MAN_OUTPUT             = man
-MAN_EXTENSION          = .3
-MAN_LINKS              = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML           = NO
-XML_OUTPUT             = xml
-XML_SCHEMA             = 
-XML_DTD                = 
-XML_PROGRAMLISTING     = YES
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF   = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX = 
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor   
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = YES
-EXPAND_ONLY_PREDEF     = YES
-SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = 
-INCLUDE_FILE_PATTERNS  = 
-PREDEFINED             = 
-EXPAND_AS_DEFINED      = 
-SKIP_FUNCTION_MACROS   = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references   
-#---------------------------------------------------------------------------
-TAGFILES               = 
-GENERATE_TAGFILE       = "api-c++/@PROJECT_NAME@DoxygenTagfile"
-ALLEXTERNALS           = NO
-EXTERNAL_GROUPS        = YES
-PERL_PATH              = /usr/bin/perl
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool   
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = YES
-MSCGEN_PATH            = /Applications/Doxygen.app/Contents/Resources/
-HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = NO
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = YES
-GROUP_GRAPHS           = YES
-UML_LOOK               = NO
-TEMPLATE_RELATIONS     = YES
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
-CALL_GRAPH             = NO
-CALLER_GRAPH           = NO
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
-DOT_IMAGE_FORMAT       = png
-DOT_PATH               = 
-DOTFILE_DIRS           = 
-DOT_GRAPH_MAX_NODES    = 50
-MAX_DOT_GRAPH_DEPTH    = 0
-DOT_TRANSPARENT        = NO
-DOT_MULTI_TARGETS      = NO
-GENERATE_LEGEND        = YES
-DOT_CLEANUP            = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine   
-#---------------------------------------------------------------------------
-SEARCHENGINE           = YES

docs/DoxyfilePython.in

-# Doxyfile 1.5.3
-
-#---------------------------------------------------------------------------
-# Project related configuration options
-#---------------------------------------------------------------------------
-DOXYFILE_ENCODING      = UTF-8
-PROJECT_NAME           = @PROJECT_NAME@
-PROJECT_NUMBER         = 
-OUTPUT_DIRECTORY       = 
-CREATE_SUBDIRS         = NO
-OUTPUT_LANGUAGE        = English
-BRIEF_MEMBER_DESC      = YES
-REPEAT_BRIEF           = YES
-ABBREVIATE_BRIEF       = 
-ALWAYS_DETAILED_SEC    = NO
-INLINE_INHERITED_MEMB  = NO
-FULL_PATH_NAMES        = NO
-STRIP_FROM_PATH        = 
-STRIP_FROM_INC_PATH    = 
-SHORT_NAMES            = NO
-JAVADOC_AUTOBRIEF      = YES
-QT_AUTOBRIEF           = NO
-MULTILINE_CPP_IS_BRIEF = NO
-DETAILS_AT_TOP         = YES
-INHERIT_DOCS           = YES
-SEPARATE_MEMBER_PAGES  = NO
-TAB_SIZE               = 4
-ALIASES                = 
-OPTIMIZE_OUTPUT_FOR_C  = NO
-OPTIMIZE_OUTPUT_JAVA   = YES
-BUILTIN_STL_SUPPORT    = NO
-CPP_CLI_SUPPORT        = NO
-DISTRIBUTE_GROUP_DOC   = YES
-SUBGROUPING            = YES
-#---------------------------------------------------------------------------
-# Build related configuration options
-#---------------------------------------------------------------------------
-EXTRACT_ALL            = YES
-EXTRACT_PRIVATE        = NO
-EXTRACT_STATIC         = NO
-EXTRACT_LOCAL_CLASSES  = YES
-EXTRACT_LOCAL_METHODS  = NO
-EXTRACT_ANON_NSPACES   = NO
-HIDE_UNDOC_MEMBERS     = NO
-HIDE_UNDOC_CLASSES     = NO
-HIDE_FRIEND_COMPOUNDS  = NO
-HIDE_IN_BODY_DOCS      = YES
-INTERNAL_DOCS          = NO
-CASE_SENSE_NAMES       = YES
-HIDE_SCOPE_NAMES       = YES
-SHOW_INCLUDE_FILES     = YES
-INLINE_INFO            = YES
-SORT_MEMBER_DOCS       = YES
-SORT_BRIEF_DOCS        = NO
-SORT_BY_SCOPE_NAME     = NO
-GENERATE_TODOLIST      = YES
-GENERATE_TESTLIST      = YES
-GENERATE_BUGLIST       = YES
-GENERATE_DEPRECATEDLIST= YES
-ENABLED_SECTIONS       = 
-MAX_INITIALIZER_LINES  = 30
-SHOW_USED_FILES        = YES
-SHOW_DIRECTORIES       = YES
-FILE_VERSION_FILTER    =
-SHOW_NAMESPACES        = NO
-SHOW_FILES             = NO
-SHOW_DIRECTORIES       = NO
-#---------------------------------------------------------------------------
-# configuration options related to warning and progress messages
-#---------------------------------------------------------------------------
-QUIET                  = NO
-WARNINGS               = YES
-WARN_IF_UNDOCUMENTED   = YES
-WARN_IF_DOC_ERROR      = YES
-WARN_NO_PARAMDOC       = NO
-WARN_FORMAT            = "$file:$line: $text    "
-WARN_LOGFILE           = 
-#---------------------------------------------------------------------------
-# configuration options related to the input files
-#---------------------------------------------------------------------------
-INPUT                  = "@CMAKE_BINARY_DIR@/python/simtk/openmm" "@CMAKE_BINARY_DIR@/python/simtk/openmm/app"
-INPUT_ENCODING         = UTF-8
-FILE_PATTERNS          = 
-RECURSIVE              = NO
-EXCLUDE                = 
-EXCLUDE_SYMLINKS       = NO
-EXCLUDE_PATTERNS       = 
-EXCLUDE_SYMBOLS        = SerializationNode SerializationProxy SwigPyIterator
-EXAMPLE_PATH           = 
-EXAMPLE_PATTERNS       = 
-EXAMPLE_RECURSIVE      = NO
-IMAGE_PATH             = 
-INPUT_FILTER           = "@PYTHON_EXECUTABLE@ @CMAKE_BINARY_DIR@/python/filterPythonFiles.py"
-FILTER_PATTERNS        = 
-FILTER_SOURCE_FILES    = YES
-#---------------------------------------------------------------------------
-# configuration options related to source browsing
-#---------------------------------------------------------------------------
-SOURCE_BROWSER         = NO
-INLINE_SOURCES         = NO
-STRIP_CODE_COMMENTS    = YES
-REFERENCED_BY_RELATION = YES
-REFERENCES_RELATION    = YES
-REFERENCES_LINK_SOURCE = YES
-USE_HTAGS              = NO
-VERBATIM_HEADERS       = YES
-#---------------------------------------------------------------------------
-# configuration options related to the alphabetical class index
-#---------------------------------------------------------------------------
-ALPHABETICAL_INDEX     = NO
-COLS_IN_ALPHA_INDEX    = 5
-IGNORE_PREFIX          = 
-#---------------------------------------------------------------------------
-# configuration options related to the HTML output
-#---------------------------------------------------------------------------
-GENERATE_HTML          = YES
-HTML_OUTPUT            = api-python
-HTML_FILE_EXTENSION    = .html
-HTML_HEADER            = 
-HTML_FOOTER            = 
-HTML_STYLESHEET        = 
-HTML_ALIGN_MEMBERS     = YES
-GENERATE_HTMLHELP      = NO
-HTML_DYNAMIC_SECTIONS  = YES
-CHM_FILE               = 
-HHC_LOCATION           = 
-GENERATE_CHI           = NO
-BINARY_TOC             = NO
-TOC_EXPAND             = NO
-DISABLE_INDEX          = NO
-ENUM_VALUES_PER_LINE   = 4
-GENERATE_TREEVIEW      = YES
-TREEVIEW_WIDTH         = 250
-#---------------------------------------------------------------------------
-# configuration options related to the LaTeX output
-#---------------------------------------------------------------------------
-GENERATE_LATEX         = NO
-LATEX_OUTPUT           = latex
-LATEX_CMD_NAME         = latex
-MAKEINDEX_CMD_NAME     = makeindex
-COMPACT_LATEX          = NO
-PAPER_TYPE             = a4wide
-EXTRA_PACKAGES         = 
-LATEX_HEADER           = 
-PDF_HYPERLINKS         = NO
-USE_PDFLATEX           = NO
-LATEX_BATCHMODE        = NO
-LATEX_HIDE_INDICES     = NO
-#---------------------------------------------------------------------------
-# configuration options related to the RTF output
-#---------------------------------------------------------------------------
-GENERATE_RTF           = NO
-RTF_OUTPUT             = rtf
-COMPACT_RTF            = NO
-RTF_HYPERLINKS         = NO
-RTF_STYLESHEET_FILE    = 
-RTF_EXTENSIONS_FILE    = 
-#---------------------------------------------------------------------------
-# configuration options related to the man page output
-#---------------------------------------------------------------------------
-GENERATE_MAN           = NO
-MAN_OUTPUT             = man
-MAN_EXTENSION          = .3
-MAN_LINKS              = NO
-#---------------------------------------------------------------------------
-# configuration options related to the XML output
-#---------------------------------------------------------------------------
-GENERATE_XML           = NO
-XML_OUTPUT             = xml
-XML_SCHEMA             = 
-XML_DTD                = 
-XML_PROGRAMLISTING     = YES
-#---------------------------------------------------------------------------
-# configuration options for the AutoGen Definitions output
-#---------------------------------------------------------------------------
-GENERATE_AUTOGEN_DEF   = NO
-#---------------------------------------------------------------------------
-# configuration options related to the Perl module output
-#---------------------------------------------------------------------------
-GENERATE_PERLMOD       = NO
-PERLMOD_LATEX          = NO
-PERLMOD_PRETTY         = YES
-PERLMOD_MAKEVAR_PREFIX = 
-#---------------------------------------------------------------------------
-# Configuration options related to the preprocessor   
-#---------------------------------------------------------------------------
-ENABLE_PREPROCESSING   = YES
-MACRO_EXPANSION        = YES
-EXPAND_ONLY_PREDEF     = YES
-SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = 
-INCLUDE_FILE_PATTERNS  = 
-PREDEFINED             = 
-EXPAND_AS_DEFINED      = 
-SKIP_FUNCTION_MACROS   = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to external references   
-#---------------------------------------------------------------------------
-TAGFILES               = 
-GENERATE_TAGFILE       = "api-python/@PROJECT_NAME@DoxygenTagfile"
-ALLEXTERNALS           = NO
-EXTERNAL_GROUPS        = YES
-PERL_PATH              = /usr/bin/perl
-#---------------------------------------------------------------------------
-# Configuration options related to the dot tool   
-#---------------------------------------------------------------------------
-CLASS_DIAGRAMS         = YES
-MSCGEN_PATH            = /Applications/Doxygen.app/Contents/Resources/
-HIDE_UNDOC_RELATIONS   = YES
-HAVE_DOT               = NO
-CLASS_GRAPH            = YES
-COLLABORATION_GRAPH    = YES
-GROUP_GRAPHS           = YES
-UML_LOOK               = NO
-TEMPLATE_RELATIONS     = YES
-INCLUDE_GRAPH          = YES
-INCLUDED_BY_GRAPH      = YES
-CALL_GRAPH             = NO
-CALLER_GRAPH           = NO
-GRAPHICAL_HIERARCHY    = YES
-DIRECTORY_GRAPH        = YES
-DOT_IMAGE_FORMAT       = png
-DOT_PATH               = 
-DOTFILE_DIRS           = 
-DOT_GRAPH_MAX_NODES    = 50
-MAX_DOT_GRAPH_DEPTH    = 0
-DOT_TRANSPARENT        = NO
-DOT_MULTI_TARGETS      = NO
-GENERATE_LEGEND        = YES
-DOT_CLEANUP            = YES
-#---------------------------------------------------------------------------
-# Configuration::additions related to the search engine   
-#---------------------------------------------------------------------------
-SEARCHENGINE           = YES